Imported Upstream version 3.0.2-20060113upstream/3.0.2-20060113

1 files changed, 104 insertions, 15 deletions

diff --git a/USAGE b/USAGE
index d627daf..1ff1857 100755
--- a/USAGE
+++ b/USAGE
@@ -185,27 +185,25 @@ detects many file types (text, PDF, most image formats) and together
 with ImageMagick (for images) and GNU/ESP/AFPL GhostScript 6.51 or
 newer (for PDF) it converts them to PostScript. The other tools
 convert only text files. The tool you have installed is auto-detected
-by foomatic-rip and used automatically if
-necessary. PPR needs this tool only for printing the option
-list, and CUPS does not need it at all. PPR and CUPS use internal filters for printing non-PostScript files.
+by foomatic-rip and used automatically if necessary. PPR needs this
+tool only for printing the option list, and CUPS does not need it at
+all. PPR and CUPS use internal filters for printing non-PostScript
+files.
 
-If you have a multi-function device from HP, install HPOJ from
+If you have a printer or multi-function device from HP, install HPLIP from
 
-   http://hpoj.sourceforge.net/
+   http://hpinkjet.sourceforge.net/
 
 before starting to set up printer queues with foomatic-filters. This
-is needed for printing on USB devices and for scanning and photo
-memory card access on all devices. If you use CUPS 1.1.12 or newer
-together with the old HPOJ 0.8, you need also the latest "ptal"
-backend script from
+is needed for printing on certain USB devices and for scanning and
+photo memory card access on all devices. It also adds maintenance
+functionality for inkjets, reporting of ink or toner levels and
+printer status, and also remote readout of the printers front-panel
+LCD. CUPS is required as the printing system when HPLIP is used.
 
-   http://www.hornclan.com/~mark/cups/
+Note: The "hp" CUPS backend and "beh" (see below) cannot be used
+together.
 
-License information and installation instructions for this script you
-find in the beginning of the script itself. See also the end of the
-"Adding a queue" section in this file to see how to use this script.
-
-The "ptal" backend script is already included in HPOJ 0.9.
 
 
 Setting up printers
@@ -243,3 +241,94 @@ Usage of PPD files (for all spoolers):
 
    http://www.linuxprinting.org/ppd-doc.html
 
+
+
+beh - Backend Error Handler
+---------------------------
+
+A wrapper for CUPS backends to make error handling configurable
+
+Usually, if a CUPS backend exits with an error status other than zero
+(for example if a printer is not turned on or not reachable on the
+network), CUPS disables the print queue and one can only print again
+if a system administrator re-enables the queue manually. Even restarting
+CUPS (or rebooting) does not re-enable disabled queues.
+
+For system administrators this can get annoying, for newbie users
+who are not aware of this problem it looks like that CUPS is severely
+broken. They remove and re-install print queues, getting on the nerves
+of distro install support, people, or even switch back to a proprietary
+operating system.
+
+This script makes the handling of such backend errors configurable, so
+that the problem can easily be worked around. The new possibilities are:
+
+ - Let queues simply not being disabled. Simple approach, but job gets 
+   lost.
+
+ - Repeat a given number of times.
+
+ - Repeat infinitely often, until the job gets finally through. This
+   is the standard of LPRng, and it eliminates loss of the job.
+
+ - The interval between two attemts to run the backend can also be
+   configured.
+
+ - Configuration is done independently for each print queue. So local
+   printers and network printers can be treated differently.
+
+
+Usage: 
+
+Make sure "beh" is in the CUPS backend directory (usually
+/usr/lib/cups/backend/) and world-readable and -executable. Restart
+CUPS (usually "killall -HUP cupsd" or "/etc/init.d/cups restart"). If
+all is correct "lpinfo -v" should have "beh" in its output.
+
+Then activate "beh" for your print queue(s) with command(s) like this:
+
+lpadmin -p <queue name> -E -v beh:/<dd>/<att>/<delay>/<originaluri>
+
+with 
+  <queue name>:     The name of your print queue
+  <dd>:             Don't Disable, if "1", beh always exits with zero
+                    status, so the queue gets never disabled when the
+                    original backend exits with an error. "0" carries
+                    the error status of the last call of the backend
+                    (after <att> retries) on to CUPS, so the queue
+                    usually gets disabled.
+  <att>:            Attempts, number of attempts to recall the backend
+                    in case of an error. "0" means infinite retries. In
+                    this case <dd> gets meaningless.
+  <delay>:          Delay between two attempts to call the beckend, to
+                    be given in seconds and as an integer number.
+                    Meaningless if <att> is one.
+  <originaluri>:    The original URI, which your queue had before. Can 
+                    be determined with "lpstat -v".
+
+All parameters, especially, <dd>, <att>, and <delay> have always to
+be specified, even if one of them is meaningless due to the setting of
+the others.
+
+beh works with every backend except the "hp" backend of HPLIP.
+
+Example URIs:
+
+beh:/1/3/5/socket://printer:9100
+
+  On the network printer with host name "printer" it is tried to access
+  3 times with 5 second delays between the attempts. If the job still
+  fails, the queue is not disabled (and the job discarded).
+
+beh:/0/10/60/socket://printer:9100
+
+  Retry 10 times in one minute intervals, disable the queue when still
+  not succeeding.
+
+beh:/1/0/60/usb://Brother/HL-5040%20series
+
+  On a Brother HL-5040 on the USB try infinitely often until the printer
+  comes back, in intervals of one minute. This way the job does not get
+  lost when the printer is turned off and one can intendedly delay
+  printing by simply switching off the printer. The ideal configuration
+  for desktop printers and/or home users.