Re: (Re-)Structuring NetBSD user documentation

["James K. Lowden" <jklowden%schemamania.org@localhost>]

On Thu, 4 Oct 2012 11:16:50 +0000
David Holland <dholland-docs%netbsd.org@localhost> wrote:

> Rather than tackle your points one by one, I'm going to try to write a
> single response, to avoid getting the outline lost in a pile of
> details.

David, that was a tour de force.  I've been wallowing in the
doc bog for 10 years now, I couldn't have said it better myself.  

Having used TeX, Docbook, ms, mdoc, perldoc, and markdown, not to
mention HTML, my hands-down favorite is troff & co.  The others offer
no particular technical advantage.  (They may be more familiar to
one person or another, "easier" by some estimation.)   

I would break down the shelf problem thus:

1.  The "one file" problem, a/ka/ the "mutiple media" problem.  Paper,
bitmapped graphics, and VT100-style terminals have different
capabilities.  To write one file that displays each at its best is
difficult, a skill in its own right.  Every source file thus tends to
favor one format or the other.  Better tools could mitigate that, but
the progress vector -- rate and direction -- don't bode well.  

2.  The "more is less" problem.  A pun.  less(1) is not enough.  It's
great for quickly loading a manual and searching  it.  I can never
remember, for example, what each of make's :E, :R., :T, etc. 
variable modifiers does, and 

        $ man make
           /:E

gets me the answer in a hurry.  But less has no notion of links or toc,
which makes using e.g. part 3 of the manual less convenient than it
could be.  

We need a graphical mdoc browser better than xman or xpdf. 
Doug McIlroy suggests Pike's Acme for the purpose because it could be
programmed to recognize .SA as links.  

3.  mdoc (or similar) to HTML.  This is undersupported, but there's no
fundamental reason it can't work; all the information HTML needs is
available in the source.  Consider unroff and troff2page
(http://www-rn.informatik.uni-bremen.de/software/unroff/,
http://www.ccs.neu.edu/home/dorai/troff2page/index.html). OTOH HTML is
optional if a better xman appears, especially if that better xman
understands HTTP.  

If these problems were solved, an expanded shelf in /usr/share/doc,
written entirely in groff macro sets (mdoc mostly, but also man and ms,
perhaps others) could be used equally well in HTML, X, and xterm.  But
there is another, even harder

4.  Prejudice.  No one approaching the problem initially thinks groff
is anything except old-fashioned.  It's remarkably hard to convince
someone that 

        .Pp
        paragraph

is just as good as 

        <p>paragraph</p>

when they "know" that rules about which column something has to be in
went out with column 7 in Cobol.  

Markup designers to a one always intend a markup-aware editor for the
purpose of authoring documents.  I note that except for lyx we haven't
seen that happen in the free software world, certainly nothing on the
order of Interleaf.  Because troff has no such pretense, it is more
tractable in a text editor.  

I suppose troff, like scotch, is an acquired taste.  

5.  Editors, the people.  Documents need editors, and document
collections need curators.  If someone wanted that job today, would
anyone give it to him?  Or would the first new directory
in /usr/share/doc start a 50-post discussion of why and why not?  

6.  Technical debt.  The weight of existing work in formats other than
groff, and the on-going writing of documents for packages that will
never adopt troff as their documentation source language.  This
suggests to me that man(1) needs to be smarter, so that "man foo" finds
mdoc, html, and ps documents, and adapts to X and non-X environments in
the way e.g. emacs does.  

I'll add one more, something technically feasible that no one's talking
about.  (You read it here first.)

Static analysis tools are getting better.  Is now feasible to analyze
the whole NetBSD oeuvre and enumerate every possible value of errno for
every library function. Some of those values are bugs (must be); others
are simply undocumented.  It wouild be no real challenge to validate
the documentation against such a list.  Similarly every getopt(3)
input, every parameter, and every return code.  I bet the answers would
be eye-opening, and I know the documentation would only be improved.  

Finding the problem is easy, right?  How to chip off just one corner?  

--jkl