Re: <OK> [Groff] Simplifying groff documentation

[Michael(tm) Smith]

M Bianchi <address@hidden>, 2006-12-22 20:00 -0500:

> The value of man pages is not the markup language.
> The value is (when done right):
> 
>       structured, standardized presentation
>               NAME, SYNOPSIS, DESCRIPTION, OPTIONS, SEE ALSO, BUGS
> 
>       standardized nomenclature
>               e.g. standard output, standard error output, ...
> 
>       language, reviewed and refined over time, that aims at clarity of
>       thought and expression
> 
>       a focus on economy of expression; man pages are reference documents not
>       "a good read".  Brief accuracy is valued over methodic instruction.
> 
>       avoidance of novel-like plot development and language, cute and clever
>       phraseology, snide comments about the competition, etc.
> 
>       relevant cross references (aka SEE ALSO)

I agree completley with all that. The *roff standard of man pages
has definitely helped to ensure consistency of structure and style
in man pages. But none of that would be lost if the source were
marked up in DocBook instead, because the DocBook Refentry
structure was modeled on *roff man-page structure from the beginning.

> What is broken with man pages _is_ the fact that nroff/troff/groff is 
> no-longer
> lingua-franca of developers.  But then neither is the  info  format.

Thank god that the info format isn't. Anyway, I don't know that
the world will ever again see a day when any one markup system for
documentation is lingua-franca among most developers.

> HTML is not an answer because it is not widely understood among developers and
> is as much an assembly language as *roff and latex.

It seems to me there's not a whole lot to understand in HTML. It
is extremely simple by design.

  --Mike

-- 
Michael(tm) Smith
http://www.w3.org/People/Smith/