"Fossies" - the Fresh Open Source Software Archive 
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the latest
Fossies "Diffs" side-by-side code changes report for "USAGE":
4.0.17_vs_4.0-20160212.
1
2 Foomatic 4.0.17
3 ===============
4
5 foomatic-filters
6 ----------------
7
8 Filter scripts used by the printer spoolers to convert the incoming
9 PostScript data into the printer's native format using a
10 printer/driver specific, but spooler-independent PPD file.
11
12 Till Kamppeter <till.kamppeter@gmail.com>
13 Lars Uebernickel <larsuebernickel@gmx.de>
14
15 http://www.openprinting.org/
16
17 This usage documentation file is written by Till Kamppeter
18
19
20 Intro
21 -----
22
23 Foomatic is a database providing information about the usage of
24 printers with Unix-like operating systems (Linux, Solaris, ...).
25
26 The applications of these operating systems send PostScript or PDF to
27 the printer queues. Therefore one usually hands over the PostScript
28 directly to a PostScript printer (sometimes with some inserted
29 PostScript commands for options) or uses Ghostscript for generating
30 the data format the printer needs from PostScript or PDF input. This
31 is done by the printer spooler which also stores the data in a spool
32 directory when the printer is still occupied by another job, transmits
33 the data to a print server in the network, and so on.
34
35 The printer drivers for non-PostScript printers are either compiled
36 into Ghostscript, a plug-in for Ghostscript (e. g. IJS drivers), or
37 they are an extra filter which converts a generic bitmap generated by
38 Ghostscript into the printer's data format. For this the spooler has
39 to call complicated command lines of Ghostscript and the extra filter
40 (if needed). The user of a Unix-like operating system normally does
41 not see these command lines because an installation program takes
42 appropriate filter scripts and/or description files from a database
43 and assigns them to the printer queue.
44
45 Widely used databases were the RHS-Printfilters and the APS
46 filters. Their disadvantages were that they only supported one spooler
47 (LPD/LPRng) and only a small part of the driver's options (mostly page
48 size and resolution). Foomatic supports all options of the drivers and
49 all known spoolers (LPD, LPRng, GNUlpr, CUPS, Solaris LP, PPR, PDQ,
50 CPS, direct spooler-less printing). In addition, all known free
51 software printer drivers are supported. Foomatic also supports
52 printing of various non-PostScript/PDF file types for spoolers which
53 do not support these by themselves (LPD, LPRng, GNUlpr, spooler-less
54 printing). To enable this feature you need to have "a2ps", "enscript",
55 "mpage", or "paps" installed.
56
57 Another problem is that the way how to install queues, to print files,
58 and to handle jobs is very different with different spoolers. LPD for
59 example requires editing of configuration files for adding a queue,
60 whereas CUPS and PPR have specialized command line utilities. Foomatic
61 puts a layer between the applications and the spoolers so that one has
62 a common, spooler-independent command line interface for all spoolers,
63 so that switching of spoolers or administration of a network with
64 different spoolers gets much easier, because for the same operations
65 there are the same commands, independent of the spooler.
66
67 This command line interface can also be used as a base for
68 spooler-independent graphical frontends.
69
70
71 Installation
72 ------------
73
74 Foomatic runs on all systems where one can run the Perl
75 interpreter and Ghostscript.
76
77 foomatic-filters needs the Perl interpreter for beh (Backend Error
78 Handler) and the test suite.
79
80 To build foomatic-rip you need a C compiler and its standard libraries.
81
82 To run beh (Backend Error Handler) or the test suite a Perl interpreter
83 (5.6.0 and newer) is needed.
84
85 To connect to remote printers with a non-CUPS printing system, you
86 need additional connectivity software (as "rlpr", "nc", "smbspool',
87 ...). To print non-PostScript/PDF files with LPD, LPRng, GNUlpr, or
88 without spooler, you will need a2ps, enscript, mpage, paps, or similar
89 filters which convert non-PostScript files to PostScript. a2ps,
90 enscript, mpage, and paps will be automatically used by the scripts
91 when they are installed.
92
93 Download sources:
94 rlpr: http://freshmeat.net/projects/rlpr/ or
95 http://www.openprinting.org/download/printing/
96 netcat: http://freshmeat.net/projects/netcat/
97
98 This package does not require any other Foomatic package. it can be
99 used with PPD files downloaded from the OpenPrinting site, with
100 manufacturer-supplied PPDs for PostScript printers, and probably with
101 other PPD files.
102
103 For non-PostScript printers one also needs Ghostscript (5.50 or newer,
104 GPL Ghostscript 8.63 or newer highly recommended) and the appropriate
105 printer driver.
106
107 For drivers which have to be compiled into Ghostscript ("Execution
108 style: Ghostscript built-in" on the driver pages on the OpenPrinting
109 site) check with "gs -h" whether the driver is in your Ghostscript. If
110 not you need to compile the driver into your Ghostscript or use a
111 Ghostscript version which already contains it (preferably GPL
112 Ghostscript 8.63 or newer).
113
114 If the driver page says "Execution style: Uniprint", it is much
115 easier, check whether the appropriate ".upp" file is in one of the
116 directories listed under "Search path:" in the end of the "gs -h"
117 output. Copy the ".upp" file to one of these directories when it was
118 not there already.
119
120 The third type of driver is marked with "Execution style: Filter",
121 this means, that you have to install a filter executable in addition
122 to Ghostscript. Check with "which <name of the filter>" whether the
123 filter is already there, otherwise download and install the
124 appropriate package.
125
126 foomatic-filters can be installed using these commands (if you have
127 downloaded this package from the BZR repository, run
128 "./make_configure" at first, for that you will also need the
129 "autoconf" and "aclocal" utilities, "aclocal" is in the "automake"
130 package in some distributions):
131
132 ./configure
133 make
134 make install
135
136 "make install" must be run as "root", the other commands can be run as
137 a normal user.
138
139 The "configure" script will auto-detect where the programs have to be
140 installed and where the Perl interpreter is located. If "configure"
141 fails because of something not being installed, do
142
143 rm -rf config.cache autom*.cache
144
145 before you run "configure" again (after installing the missing parts).
146
147 By default, foomatic-filters is installed into subdirectories of
148 /usr/local (e. g. /usr/local/bin/foomatic-rip), to get it into
149 subdirectories of /usr (/usr/bin/foomatic-rip), enter:
150
151 ./configure --prefix=/usr --sysconfdir=/etc
152 make
153 make install
154
155 There are other things which can be adjusted by options on the
156 "configure" command line, enter "./configure --help" for more
157 info. You can also modify variables in the beginning of the "Makefile"
158 after running "configure", but note that every run of "configure"
159 re-creates the "Makefile".
160
161 You can also run Foomatic out of its source directory (for example
162 when you want to try it out, or when you don't have root
163 access). Therefore enter (can be done as a normal user):
164
165 ./configure
166 make inplace
167
168 and enter the commands with "./" in the beginning
169 (e. g. "./foomatic-rip ...", "man ./foomatic-rip.1"). This also works
170 on a machine where a system-wide Foomatic is already installed.
171
172 In addition, if you do not use CUPS, you should install a utility to
173 make PostScript out of non-PostScript files, so that you can print
174 those non-PostScript files and also a list of available options using
175 the "docs" option. The supported utilities are "a2ps"
176 (http://www-inf.enst.fr/~demaille/a2ps/), "enscript"
177 (http://people.ssh.fi/mtr/genscript/), "mpage"
178 (http://www.mesa.nl/pub/mpage), and "paps"
179 (http://paps.sourceforge.net/). Recommended is "a2ps" because it
180 detects many file types (text, most image formats) and together with
181 ImageMagick (for images) and Ghostscript it converts them to PostScript.
182 The other tools convert only text files. However at present paps
183 is the only one to support files encoded in utf-8. The tool you have
184 installed is auto-detected by foomatic-rip and used automatically if
185 necessary. PPR needs this tool only for printing the option list, and
186 CUPS does not need it at all. PPR and CUPS use internal filters for
187 printing non-PostScript files.
188
189 If you have a printer or multi-function device from HP, install HPLIP from
190
191 http://hplipopensource.com/
192
193 before starting to set up printer queues with foomatic-filters. This
194 is needed for printing on certain USB devices and for scanning and
195 photo memory card access on all devices. It also adds maintenance
196 functionality for inkjets, reporting of ink or toner levels and
197 printer status, and also remote readout of the printers front-panel
198 LCD. CUPS is required as the printing system when HPLIP is used.
199
200 Note: The "hp" CUPS backend and "beh" (see below) cannot be used
201 together.
202
203
204
205 Setting up printers
206 -------------------
207
208 If you have "foomatic-db-engine" installed, see the USAGE file there.
209
210 If not, see, depending on your spooler:
211
212 CUPS:
213
214 http://www.openprinting.org/cups-doc.html
215
216 LPD, LPRng, GNUlpr:
217
218 http://www.openprinting.org/lpd-doc.html
219
220 PPR:
221
222 http://www.openprinting.org/ppr-doc.html
223
224 PDQ:
225
226 http://www.openprinting.org/pdq-doc.html
227
228 CPS:
229
230 http://www.tww.cx/cps.php
231
232 Direct, spooler-less printing:
233
234 http://www.openprinting.org/direct-doc.html
235
236 Usage of PPD files (for all spoolers):
237
238 http://www.openprinting.org/ppd-doc.html
239
240
241
242 beh - Backend Error Handler
243 ---------------------------
244
245 A wrapper for CUPS backends to make error handling configurable
246
247 Usually, if a CUPS backend exits with an error status other than zero
248 (for example if a printer is not turned on or not reachable on the
249 network), CUPS disables the print queue and one can only print again
250 if a system administrator re-enables the queue manually. Even restarting
251 CUPS (or rebooting) does not re-enable disabled queues.
252
253 For system administrators this can get annoying, for newbie users
254 who are not aware of this problem it looks like that CUPS is severely
255 broken. They remove and re-install print queues, getting on the nerves
256 of distro install support, people, or even switch back to a proprietary
257 operating system.
258
259 This script makes the handling of such backend errors configurable, so
260 that the problem can easily be worked around. The new possibilities are:
261
262 - Let queues simply not being disabled. Simple approach, but job gets
263 lost.
264
265 - Repeat a given number of times.
266
267 - Repeat infinitely often, until the job gets finally through. This
268 is the standard of LPRng, and it eliminates loss of the job.
269
270 - The interval between two attemts to run the backend can also be
271 configured.
272
273 - Configuration is done independently for each print queue. So local
274 printers and network printers can be treated differently.
275
276
277 Usage:
278
279 Make sure "beh" is in the CUPS backend directory (usually
280 /usr/lib/cups/backend/) and world-readable and -executable. Restart
281 CUPS (usually "killall -HUP cupsd" or "/etc/init.d/cups restart"). If
282 all is correct "lpinfo -v" should have "beh" in its output.
283
284 Then activate "beh" for your print queue(s) with command(s) like this:
285
286 lpadmin -p <queue name> -E -v beh:/<dd>/<att>/<delay>/<originaluri>
287
288 with
289 <queue name>: The name of your print queue
290 <dd>: Don't Disable, if "1", beh always exits with zero
291 status, so the queue gets never disabled when the
292 original backend exits with an error. "0" carries
293 the error status of the last call of the backend
294 (after <att> retries) on to CUPS, so the queue
295 usually gets disabled.
296 <att>: Attempts, number of attempts to recall the backend
297 in case of an error. "0" means infinite retries. In
298 this case <dd> gets meaningless.
299 <delay>: Delay between two attempts to call the beckend, to
300 be given in seconds and as an integer number.
301 Meaningless if <att> is one.
302 <originaluri>: The original URI, which your queue had before. Can
303 be determined with "lpstat -v".
304
305 All parameters, especially, <dd>, <att>, and <delay> have always to
306 be specified, even if one of them is meaningless due to the setting of
307 the others.
308
309 beh works with every backend except the "hp" backend of HPLIP.
310
311 Example URIs:
312
313 beh:/1/3/5/socket://printer:9100
314
315 On the network printer with host name "printer" it is tried to access
316 3 times with 5 second delays between the attempts. If the job still
317 fails, the queue is not disabled (and the job discarded).
318
319 beh:/0/10/60/socket://printer:9100
320
321 Retry 10 times in one minute intervals, disable the queue when still
322 not succeeding.
323
324 beh:/1/0/60/usb://Brother/HL-5040%20series
325
326 On a Brother HL-5040 on the USB try infinitely often until the printer
327 comes back, in intervals of one minute. This way the job does not get
328 lost when the printer is turned off and one can intendedly delay
329 printing by simply switching off the printer. The ideal configuration
330 for desktop printers and/or home users.