Re: [Groff] Documentation for -mom

[Peter Schaffter]

Ingo --

On Fri, Sep 19, 2014, Ingo Schwarze wrote:
> Given that the build systems disables building HTML documentation
> when some support software is missing on the target system and
> that the main mom documentation is (very unfortunately, but that's
> the current state of affairs) HTML, we end up in a situation where
> some groff installations do not include full mom documentation.

The attached patch to /contrib/mom/Makefile.sub should ensure that
mom's documentation gets installed (and uninstalled) regardless
of whether support software for building HTML documentation is
missing.

On Sun, Sep 21, 2014, Peter Schaffter wrote:
>> a lot of mom users would disagree that having the documentation
>> in html is unfortunate. :)

> Well, what i mean is this.  In my tutorial on documentation here in
> Sofia i'm going to list seven quality criteria for software
> documentation:
> 1. correctness
>  2. completeness
>  3. conciseness
>  4. ease of access (both regarding searching and regarding the
>     required tools for viewing it); ideally, all documentation
>     should be in one place so you cannot miss it
>  5. semantic markup
>  6. ease of reading; ideally, uniform display markup and style
>  7. ease of writing; ideally, one simple, standard input language
> 
> HTML flat-out fails on criteria 4-7.

Respectfully disagree with "flat-out fails", though not because I'm
promoting HTML as a documentation standard.  Heaven forbid.

5. Well-formed css/xhtml allows for unambiguous semantic markup.

6. For ease of reading, uniform display and style are only
   achievable when the display and style are well-thought-out and
   well-rendered; a manpage at the terminal is decidedly
   sub-optimal in this regard, as my occasionally blurred vision
   will attest. :)

7. Agreed.  HTML is a PITA.

> Regarding 4, it's not just that people cannot see it in man(1)
> where documentation is expected to be, but need to install a
> browser; on top of that, apropos(1) will be completely blind to it.

Regarding 4, you omitted "ease of navigation".  Searching is one
thing, but it doesn't include being able to click on internal links
to find out what an unfamiliar term means, or how, in the case of
mom, to use a macro that's referenced in the description of another
macro's usage.  Clickable cross-references, IOW.

Some programs aren't suited for manpages, esp. those whose
documentation benefits from a table of contents, indices, and
extensive cross-linking.  Remember the bad old days of FVWM, with
its humungous, unindexed, un-cross-linked manpage?  It was correct,
complete, concise (despite its length), easy to access--and pure,
off-putting hell to wade through.

GNU tried to solve the navigation problem by foisting texinfo on
everybody, but after a couple of decades I, and many others, still
find info(1) a trial to use.

I'd never suggest that HTML should be a standard for Unix
documentation.  Manpages are essential.  However, when they can't
furnish easily-navigable information about a program's usage, some
other form of documentation is required.

Furthermore, the search-only navigation and in-a-nutshell style of
manpages can actually have the effect of discouraging program usage
if the program is large and complex.  What good is documentation
that turns people off using a program, or leaves them scratching their
heads saying, "I'll never make sense of all this"?

In instances where a manpage is clearly the wrong format for
documentation, I believe, as was for so long the case with mom, that
a manpage stub pointing to the complete documentation in another
format is the way to go since it prevents apropos(1) blindness and
tells users correctly, completely, and concisely what they need to
know, namely "go here for the documentation."

As for "installing a browser", e.g. w3m(1), is that any more trouble
than installing less(1) in order to browse manpages?

-- 
Peter Schaffter
http://www.schaffter.ca

diff
Description: Text document