[cups.bugs] Re: [LOW] STR #1830:http://localhost:631/help/options.html, thePrinting and Options page should come as a man page

[Michael Sweet]

Roger Leigh wrote:
> On 2006-07-11, Michael Sweet <mike at easysw.com> wrote:
>> wtautz wrote:
>>> Michael Sweet wrote:
>>>> [STR Closed w/o Resolution]
>>>>
>>>> We decided a long time ago that the detailed documentation would be
>>>> available on the web interface and not in the man pages - it is too hard
>>>> to maintain both sets of documentation.
>>>>
>>>> Link: http://www.cups.org/str.php?L1830
>>>> Version: 1.3-current
>>>> Fix Version: Will Not Fix
>>>>   
>>> I suppose if I can offer a solution you might accept it ? :-)
>> If by "solution" you mean some sort of documentation generator, it
>> will depend on the portability, etc.  That said, long man pages are
>> much less usable than the same content in a browser - man doesn't let
>> you scroll back and forth, print, or easily search the contents, and
>> of course you can't use images or tables...
> 
> Regarding navigation: if you use less, it is quite easy to navigate.
> less (in Debian) even does case-insensitive searching when viewing
> manual pages.  Other viewers create hyperlinks and have the same search
> capabilities you would get in a web brower.

Only Linux has GNU less by default, and depending on your settings
and Linux distribution of choice, it may not even be the default.

Searching with more or less uses regular expressions - powerful but
often frustrating/confusing for users.  Searching also only works
within the current page, and if you use "man -k keyword", it only
searches the title of the man page and (usually) requires the
user/administrator to manually run makewhatis after installing
software for it to work (fortunately Linux and IRIX do this by
default, but none of the other commercial UNIX's do...)

Finally, web-based man page viewers are certainly more powerful,
which is why we convert the man pages to HTML and include them in
the on-line help... :)

> Regarding printing: manual pages can be trivially converted to
> PostScript using the grops postprocessor.  If the manual page was
> written properly, it will give high quality output.  You can even make
> full use of typefaces and styles.  I would have to say that printing
> a manual page gives far better (and reproducible) output than printing
> HTML from a browser.

High-quality 'roff output is of course possible (that's how UNIX
started out, right? ;), however you'll find that commercial UNIX
operating systems print plain text and don't do high-quality PS
output unless you manually run troff/groff, and then only if you
have all of the optional packages installed.

> You can certainly use tables: tbl works fine in manpages (.TS/.TE).

.... but is not available by default on all platforms, and because of
the limits of console output it is only useful for very small or
simple tables.

> Images are rather more troublesome.  For really simple lines and boxes,
> pic is possible, but may render badly.

Yeah, ASCII art is a poor substitute for an image.  When I've needed
to include diagrams in a man page or other (primarily) text-based
output, I usually draw things by hand to get acceptable results.

Regardless, *maintaining* all of this in both .man and .html formats
is not something we want to do, and we've made the decision to make
the HTML documentation "more complete" with respect to tutorials and
details of specific options and settings.  Unless someone shows us a
tool that we can embed (small) in the CUPS build system or is
available on all UNIX's and can create suitable man pages and HTML
help files from a common source, that's how things will remain.

-- 
______________________________________________________________________
Michael Sweet, Easy Software Products           mike at easysw dot com
Internet Printing and Document Software          http://www.easysw.com