[Pkg-cups-devel] Bug#381252: lpoptions documentation doesn't

[sacrificial-spam-address at horizon.com]

Package: cupsys-client
Version: 1.2.2-1

The CUPS docs have a very severe case of Microsoft-itis, with lots of
friendly words and HTML that fail to actually explain the things they're
supposed to be documenting.

The lpoptions documentation explains that options are specified
as "-o <option>[=<value>]", and listed with -l.

Okay, let's try that...

HPJobRetention/Job Retention: *HPJobRetentionOff HPJobRetentionQuickCopy HPJobRetentionProof HPJobRetentionPrivate HPJobRetentionStore
HPUserName/User: *UserSystem User1 User2 User3 User4 User5 User6 User7 User8 User9 User10 User11 User12 User13 User14 User15 User16 User17 User18 User19 User20 User21 User22 User23 User24 User25 User26 User27 User28 User29 User30 User31 User32 User33 User34 User35 User36 User37 User38 User39 User40 User41 User42 User43 User44 User45 User46 User47 User48 User49 User50
HPJobHoldKey1/PIN digit 1 (for Private Job): *HoldKey0000 HoldKey1000 HoldKey2000 HoldKey3000 HoldKey4000 HoldKey5000 HoldKey6000 HoldKey7000 HoldKey8000 HoldKey9000
HPJobHoldKey2/PIN digit 2 (for Private Job): *HoldKey000 HoldKey100 HoldKey200 HoldKey300 HoldKey400 HoldKey500 HoldKey600 HoldKey700 HoldKey800 HoldKey900
HPJobHoldKey3/PIN digit 3 (for Private Job): *HoldKey00 HoldKey10 HoldKey20 HoldKey30 HoldKey40 HoldKey50 HoldKey60 HoldKey70 HoldKey80 HoldKey90
HPJobHoldKey4/PIN digit 4 (for Private Job): *HoldKey0 HoldKey1 HoldKey2 HoldKey3 HoldKey4 HoldKey5 HoldKey6 HoldKey7 HoldKey8 HoldKey9
HPwmText/Watermark: *None CompanyConfidential CompanyProprietary CompanyPrivate Confidential Copy Copyright Draft FileCopy Final ForInternalUse Preliminary Proof ReviewCopy Sample TopSecret Urgent
HPwmFont/Watermark Font: CourierB TimesB *HelveticaB
HPwmFontSize/Watermark Size: pt24 pt30 pt36 pt42 *pt48 pt54 pt60 pt66 pt72 pt78 pt84 pt90
HPwmTextAngle/Watermark Angle: Deg90 Deg75 Deg60 *Deg45 Deg30 Deg15 Deg0 DegN15 DegN30 DegN45 DegN60 DegN75 DegN90
HPwmTextStyle/Watermark Style: Narrow *Medium Wide Halo
HPwmLocation/Print Watermark: *True False
HPCollate/Collate: True *False
Smoothing/Resolution Enhancement: *True False
PageSize/Media Size: *Letter Executive Legal A4 A5 B5 w612h935 w558h774 Env10 EnvMonarch EnvDL EnvC5 EnvISOB5 Custom
PageRegion/PageRegion: Letter Executive Legal A4 A5 B5 w612h935 w558h774 Env10 EnvMonarch EnvDL EnvC5 EnvISOB5
InputSlot/Media Source: Upper ManualFeed *Middle Lower LargeCapacity Tray5 Tray6 Tray7 Tray8 Tray9 Tray10 Envelope Plain Preprinted Letterhead Transparency Prepunched Labels Bond Recycled Color Cardstock Rough
HPPaperPolicy/Fit to Page: *PromptUser NearestSizeAdjust NearestSizeNoAdjust Letter A4
HPHalftone/Levels of Gray: *PrinterDefault Enhanced Standard
Duplex/Duplex: *None DuplexNoTumble DuplexTumble
JCLResolution/Resolution: 300dpi *600dpi 1200dpi
JCLFastRes/FastRes 1200: *True False
JCLEconomode/EconoMode: *False True
OptionTrays/Number of Input Trays: *2Trays 3Trays 4Trays 5Trays 6Trays 7Trays 8Trays 9Trays 10Trays
Option3/Duplex Unit: True *False
Option4/Printer Hard Disk: True *False
Option5/Envelope Feeder: True *False
InstalledMemory/Total Printer Memory: 16MB 24-31MB 32-63MB 64-95MB 96-127MB *128-191MB 192-256MB

Wow, that doesn't look a lot like "name=value".  The asterisks are
reasonably clear, so let's assume I replace the ": " with an =, and
try to tell cups that I have a duplexer:

# lpoptions -o "Option3/Duplex Unit=True"

H'm... what I get in /etc/cups/lpoptions is
Default lp Option3/Duplex=true Unit=True

That's... very strange.  At least it tells me what happens if you
leave off the "=value" part, whaich the documentation (man page or
HTML) notably fail to.  Of course, nothing has explained if "true"
and "True" are equivalent or not.

It appears to be breaking the options apart at spaces.  I want
a space in my option name.  The lpoptions file appears to be
space-delimited, so presumably my option needs quoting.
Let's try:

# lpoptions -o "\"Option3/Duplex Unit\"=True"

That produces
Default lp Option3/Duplex=true Unit=True "Option3/Duplex=true Unit"=True

Wow, parse confusion city!

Time to RTFS... cupsys-1.22/cups/dest.c:cups_get_dests() calls
options.c:cupsParseOptions() which actually parses the string.
And... quptes are supported in the option value, but not in the
option name.  No way, no how.

Am I totally stuck?


Actually, after searching the web a whole lot, I found an example
lpoptions file that contains PostScript options, and makes
it clear that only the part before the / is the "option name"
to use.

So from
Option3/Duplex Unit: True *False

I need to figure out to type:
lpoptions -o Option3=True


Could this perhaps be explained somewhere, so that people wanting to
set options have a hope in hell of doing so?

In truth, this entire lpoptions mess could be avoided with a paragraph
on reading the raw ppd file:

"Printer-level options can be presented by the web interface or the
lpoptions command, but they are controlled by the relevant ppd file,
located in /etc/cups/ppds/<printername>.ppd.  In those files, you'll
see some "*OpenUI" lines which describe selectable options, and possible
values.  The name or value does not include the leading asterisk or the
trailing slash and following descriptive text.  Names never contain
spaces; values rarely do."

Other wishes I haven't personally suffered for lack of yet:

- An explanation of the interaction between CUPS-level options like
  job-sheets and page-ranges and printer/PPD-level options like
  HPOption_EnvFeeder?  What happens if there's a collision?
- An explanation of the other fancy option values ("collection values")
  supported in lpoptions.  The source refers to the PAPI specification,
  which is itself a bit dense.  And I can't find anywhere in the PAPI
  specification an answer to the case-sensitivity question.
- A description of what locking issues arise when manually editing a file
  and what has to be done to force a reload of the results.

It would also be nice if, given an HP LaserJet 4300 with
"HPOption_Tray3=Tray3_500" set in /etc/cups/lpoptions, the
CHECKED attribute could be set appropriately in the HTML for
https://$SERVER:631/admin/?op=set-printer-options&printer_name=$PRINTER.