Re: <OK> [Groff] Simplifying groff documentation

[Eric S. Raymond]

M Bianchi <address@hidden>:
> On Fri, Dec 22, 2006 at 06:19:15PM -0500, Eric S. Raymond wrote:
> >     :
> > But I hear you asking "Why fix what ain't broken?". 
> >     : 
> > The philosophical issue this raises about groff's place in the world
> > is simple: are we willing to accept that it's a legacy rather than
> > a primary format?
> >     :
> 
> Don't take my groff away!  (Yes, I see you did _not_ propose that.)
> I have documents from the late 1970s that I can still format and maintain.

There, there.  Nobody is going to try to pry your groff away from your
cold dead fingers. :-)
 
> 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 think you'll see from my previous reply to Ted Harding that 
I agree with this.
 
> To me, having "fully-hypertexted, Web-centric documentation" is the
> wrong goal.  Having clear, cogent and accurate documentation is.  If
> ESR's proposal creates that outcome, yippeee!  If not, boooo.

Well, of course what we want is "clear, cogent and accurate documentation".
But I can't solve *that* problem.  What I can do, and have been doing more 
or less by stealth since 2001, is lining up all the technical ducks in a
row so we can address the format and infrastructure problems.

> An input format for man page _information_ that provided the structure,
> guidance, and mechanisms to guide people into creating clear, cogent and
> accurate information, is something I would applaud.

A worthy goal, but really independent of the underlying formatting engine.
groff vs. browser makes little difference here.

> Again: the goal should be making the documentation something people
> passionately care about, so remain stay living documents forever.

I think, at least, that I may be helping ensure that the good old
stuff doesn't get lost in the transition to the big Webbed world.

> I believe that if the effort was done properly, then the content could be
> mechanically translated into any of the formats, including long, flat text
> files.  man -> docBook  would imply  docBook -> man

Well, no, actually.  DocBook -> man is easy -- you're throwing away
structure when you do that.  man -> DocBook is *hard*, because you have 
to deduce semantic structure from presentation-level cliches.  

In fact, consensus among the world's DocBook mavens was that this was
impossible to pull off -- before I, er, did it.  It required an unusual
combination of advanced compiler-jockery, familiarity with certain AI
techniques, and sheer bloody-minded persistence. 

> Could the wikipedia markup be (close to) adequate?  Something
> similar?  Standing firmly on an existing popular standard could be
> important to achieving wide acceptance.

And that's why, in the grand master plan, XML-DocBook has a central
role.  Nobody wants to read it directly -- you render to HTML or
Postscript with a stylesheet to do that.  But it makes a dandy 
format for masters and searchable archives.  Wiki markups doesn't
quite have the structural richness needed.

But the world I'm trying to get us to looks something like this:

+-------------+                                      +--------------------+
|  man pages  |-----+                           +--->|  HTML on browsers  |
+-------------+     |                          /     +--------------------+
                    |                         /
+-------------+     |         +-------------+/
|  Texinfo    |-----+-------->| XML-DocBook |
+-------------+     |         +-------------+\
                    |                         \
+-------------+     |                          \     +------------------------+
|  other      |-----+                           +--->| PostScript on printers |
+-------------+                                      +------------------------+

Multiple composition formats (including man markup) but all feeding to 
one richly-structured exchange format, which is then rendered to 
different media by stylesheets.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>