Looking for feedback: first draft of new "Examples" section for lpadmin man page
Kurt Pfeifle
kpfeifle at danka.de
Fri Jun 16 16:19:20 PDT 2006
I submitted an STR (Software Trouble Report) asking for extending each
CUPS man page by an "Example" section. It is my firm believe that docs
which provide (plenty of) examples are easier understood, and that some
degree of redundancy makes documentation better for end users.
I also pledged to look into writing drafts for each of these man pages
over the next few months (http://www.cups.org/str.php?U1781).
So here is my first quick shot at "Examples" for the lpadmin man page.
Before I go into the trouble of learning how to write the "troff" man
page source code, I'd like to get some feedback from other users about
the specific examples I'm proposing to use. So here's a start for some
added documentation redundancy!
Please first read the current (CUPS-1.2) lpadmin man page to get the
context of the examples used below:
http://www.cups.org/documentation.php/man-lpadmin.html
........
Now have a look. Test. Find bugs. Give feedback. :-)
Cheers,
Kurt
----------------------------------------------------------------------
Example 1:
----------
lpadmin -p hpljet \
-v socket://10.162.5.84:9100 \
-o printer-error-policy=retry-job \
-m laserjet.ppd
Explanation:
------------
-p : sets the printqueue name to be "hpljet"
-v : sets the backend to use the AppSocket protocol (a.k.a.
HP JetDirect), with printer IP address "10.162.5.84"
and port "9100"
-o : sets the printqueue's error policy to indefinitely
retry any job upon failure of the backend
-m : retrieves the PPD to be used from the CUPS standard
PPD directory (usually /usr/share/cups/model/) looking
for a file named "laserjet.ppd"
More Info:
----------
1) The new printqueue "hpljet" will *not* be enabled from
its inception, but rather disabled (since the -E option
was not given).
2) The PPD file associated with the new printqueue will
have been copied to /etc/cups/ppd/hpljet.ppd.
3) To list all available PPDs currently stored in the
standard PPD directory, run (as root) "lpinfo -m".
----------------------------------------------------------------------
Example 2:
----------
lpadmin -p postscript%2\2.floor \
-v ipp://infotec_is2127.danka.de/ipp \
-E \
-L "Danka DPD Office, Building 7, 2nd Floor \
-I "PostScript printer with custom watermarks" \
-P /home/kurt/PPDs/is2127.ppd
Explanation:
------------
-p : sets the printqueue name to be "postscript%2\2.floor"
-v : sets the backend to use the Internet Printing Protocol
with printer addressed by its fully qualified domain
name (requires working DNS or a valid /etc/hosts file)
with the named IPP "device URI"
-E : sets the newly created printqueue to "enabled" right
from its inception
-L : sets the named "location" string
-I : sets the named "printer info" string
-P : retrieves the PPD to be used from the absolute path+name
given
More Info:
----------
1) Printqueue names in CUPS 1.2.x can use nearly any printable
character (exceptions see section "Compatibility"). This
provides more liberty for the naming of printqueues than
there was in CUPS 1.1.x.
2) Since no specific "printer-error-policy" was given, the
default one (which is to stop the printer in case of
failure to transfer the job) will be used
3) To list all available backends (or "device URIs") currently
available for your CUPS printers, run (as root) "lpinfo -v".
----------------------------------------------------------------------
Example 3:
----------
lpadmin -p LpRn1 \
-v parallel:/dev/lp0 \
-E
Explanation:
------------
-p : sets the printqueue name to be "LpRn1"
-v : sets the backend to use a parallel connection
-E : sets the newly created printqueue to "enabled" right
from its inception
More Info:
----------
1) Since no PPD was specified (neither with -m nor with -P),
this queue will be a "raw" queue (i.e. print jobs will be
sent directly over the backend to the print device,
any filtering or sanity check); if you LpRn1 is a PostScript
printer, make sure to only send PostScript files its way.
2) CUPS printernames are not case sensitive, remember?
3) If a queue named "LpRn1" (or "lprn1", or "LPrn1" or any
other-cased variant thereof) did exist *before* you run the
above command, now this printer's backend will habe been
changed to "parallel:/" and its status to "enabled"; its
"-L" and "-I" descriptions will have remained the same,
and its PPD file be unchanged (if there was one).
----------------------------------------------------------------------
Example 4:
----------
lpadmin -E \
-U kurt \
-h cupsserver.danka.de \
-p remotecupsprinter \
-v lpd://192.168.1.101/passthru \
-E \
-m stcolor2.ppd.gz
Explanation:
------------
-E : enforces to use encryption when connecting to the
server
-U : uses the impersonation of user "kurt" to install this
printqueue
-h : installs this printqueue not on localhost, but on
remote CUPS server "cupsserver.danka.de"
-p : sets the remote printqueue name to be "remotecupsprinter"
-v : sets the backend to use the venerable LPR/LPD protocol
-E : sets the newly created printqueue to "enabled" right
from its inception
-m : this looks for the compressed file "stcolor2.ppd.gz"
in the standard CUPS PPD directory locally (!), but
upon installations transfers it to the remote CUPS
server and sets it up as the remote
/etc/cups/ppd/remotecupsprinter.ppd file for the new
printqueue
More Info:
----------
1) Note again: "-E" has different meanings (depending on
its relative position in the parameter list)
2) lpadmin can install or modify printqueues "remotely".
3) A user specified with -U needs to have all privileges
required to install the printer on the host specified;
4) If the current user does not have the lpadmin command
in his $PATH, use a full path (like /usr/sbin/lpadmin)
5) Most lpd://-driven printers are picky about the exact
device URI to address them; consult your printer manual
or your vendor hotline if you are unsure.
More information about the cups
mailing list