root / tea4cups / trunk / README @ 3395

Revision 3382, 6.0 kB (checked in by jerome, 16 years ago)

Specified link to bug tracker.

  • Property svn:keywords set to Author Date Id Rev
Line 
1# $Id$
2
3Tea4CUPS : Tee for CUPS
4
5(c) 2005, 2006, 2007 Jerome Alet <alet@librelogiciel.com>
6(c) 2005 Peter Stuge <stuge-tea4cups@cdy.org>
7This program is free software; you can redistribute it and/or modify
8it under the terms of the GNU General Public License as published by
9the Free Software Foundation; either version 2 of the License, or
10(at your option) any later version.
11
12This program is distributed in the hope that it will be useful,
13but WITHOUT ANY WARRANTY; without even the implied warranty of
14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15GNU General Public License for more details.
16
17You should have received a copy of the GNU General Public License
18along with this program; if not, write to the Free Software
19Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20
21=============================================================================
22
23Tea4CUPS resembles the *nix command 'tee', but is a CUPS backend.
24
25Tea4CUPS behaves just like any other CUPS backend, but allows you to
26modify print jobs' datas as they pass through it and to transparently
27send them to any number of outputs : other CUPS backends, files or pipes.
28
29This for example allows you to output the same print job on several
30printers at the same time, which is not possible with CUPS.
31
32Another possibility would be for example to send the same document to
33a printer, a PDF generator, a Fax, and as an attachment to an email
34message, all of this by printing it a single time.
35
36Tea4CUPS allows this by permitting you to easily plug your own
37commands into the very last stage of CUPS' filtering chain.
38
39Tea4CUPS provides three ways to launch commands :
40
41        - filters : A filter can modify the input datas before they
42                    are sent to the printer or made available to
43                    the pre and post hooks defined below.
44                    Currently a single filter can be defined
45                    per print queue.
46
47        - prehooks : these are guaranteed to be launched before the
48                     print job is sent to the real printer.
49                     Any prehook which exits -1 can cancel the
50                     print job. Any number of prehooks can be
51                     defined for a particular print queue.
52
53        - posthooks : these are guaranteed to be launched after the
54                      print job has been sent to the real printer,
55                      unless the job was previously cancelled by a
56                      prehook. Any number of posthooks can be
57                      defined for a particular print queue.
58
59To help your own commands, Tea4CUPS makes available as part of the
60environment several variables which can be used from the
61commands you use in pre and post hooks :
62
63        TEAPRINTERNAME : The print queue name.
64        TEADIRECTORY : Tea4CUPS output directory.
65        TEADATAFILE : Full name of Tea4CUPS work file (in $TEADIRECTORY).
66        TEAJOBSIZE : Job's size in bytes.
67        TEAMD5SUM : MD5 sum of the job's datas.
68        TEACLIENTHOST : Client's hostname or IP address.
69        TEAJOBID : Job's Id.
70        TEAUSERNAME : Name of the user who launched the print job.
71        TEATITLE : Job's title.
72        TEACOPIES : Number of copies requested.
73        TEAOPTIONS : Options of the print job.
74        TEAINPUTFILE : Print job's data file or empty when job read from stdin.
75        TEABILLING : Job's billing code (lp -o job-billing=SomeCode file.ps)
76        TEACONTROLFILE : Job's IPP message file (usually /var/spool/cups/c?????)
77        TEASTATUS : Original CUPS backend's exit code : ONLY AVAILABLE FROM
78                    posthooks, obviously.
79
80        None of these environment variables is available to filters.
81 
82NB : Tea4CUPS requires a version of Python >= 2.3
83
84=============================================================================
85
86Installation :
87--------------
88
89  0 - Download Tea4CUPS from :
90
91        http://www.pykota.com/software/tea4cups
92
93      and extract it :
94
95        $ tar -zxf tea4cups-x.yy.tar.gz
96
97        where x.yy is Tea4CUPS' version number.
98
99  1 - Copy the 'tea4cups' command into CUPS' backend directory,
100      for example :
101
102        $ cp tea4cups /usr/lib/cups/backend
103       
104      If you use CUPS v1.2 or higher you must do this as well :
105     
106        $ chown root.root /usr/lib/cups/backend/tea4cups
107        $ chmod 700 /usr/lib/cups/backend/tea4cups
108
109  2 - Restart CUPS in order for this new backend to be detected.
110      NB : For this to work you need CUPS 1.1.15 or higher.
111      You can use Tea4CUPS with older versions if you want, but
112      without autodetection.
113
114  3 - Either from CUPS' web interface, add new printers with
115      'Tea4CUPS managed' in front of the device's name.
116
117      Or by directly modifying CUPS' printers.conf file, or with
118      the lpadmin command line tool, just prepend each DeviceURI
119      value with 'tea4cups://'. If you modified printers.conf
120      directly instead of using lpadmin then don't forget to
121      restart CUPS.
122      (Use this last method if autodetection doesn't work because
123      the version of CUPS you use is too old)
124
125  4 - Copy tea4cups.conf into CUPS' configuration directory (where
126      cupsd.conf resides) :
127
128        $ cp tea4cups.conf /etc/cups/
129
130  5 - Modify tea4cups.conf to suit your needs. Several examples
131      are included.
132
133  6 - There's no 6 !
134
135=============================================================================
136
137Troubleshooting :
138-----------------
139
140  1 - Set "LogLevel debug2" and "MaxLogSize 0" in CUPS' cupsd.conf
141
142  2 - Restart CUPS.
143
144  3 - Set "debug: yes" in the [global] section of tea4cups.conf
145
146  4 - Print something on a print queue managed
147      by Tea4CUPS.
148
149  5 - Look at CUPS' error_log file for diagnostic and error messages.
150
151=============================================================================
152
153CUPS (Common UNIX(r) Printing System) is trademark property of Easy Software
154Products.
155
156You can download CUPS from :
157
158        http://www.cups.org
159
160=============================================================================
161
162Please report any problem to the bug tracker at http://trac.pykota.com
Note: See TracBrowser for help on using the browser.