[Groff] Re: Simplifying groff documentation

[Eric S. Raymond]

Ted Harding <address@hidden>:
> One needs, in my view, to distinguish between man-page markup
> and man-page layout. I'm of the view (though some, and especially
> texinfo fans, would probably not agree) that the man-page layout
> is very good for the user once the user is used to it. And a
> well-coordinated suite of man-pages (e.g. for 'groff') is the
> ideal reference once one has studied it and assimilated the
> links between individual related man-pages. Of course, this is
> the attitude of someone who learned Unix through the man-pages
> the "hard way" many years ago.

I don't disagree.  Man-page layout is not going to die, and it
is no part of my plans to try to make it die. 

XML-DocBook has a document type called a RefEntry which is
deliberately structured like a classic man page.  Superficially, the
reason is to have a type that man pages are easy to lift to -- which
is exactly what doclifter does.  Fundamentally, it's because the
man-page format has virtues worth preserving.

> > I want to fix the groff documentation so that it's no longer in
> > the way of automatic lifting of *everything* to HTML.  (As a side
> > benefit, the markup in the groff documentation will become easier
> > to maintain.) The only downside might be a slight decrease in the
> > visual quality of the printed versions -- in particular, command
> > synopses might no longer look quite as pretty.
> 
> So long as they remain as clear as they should be, and retain their
> overall layout, a slight aesthetic detriment should be acceptable. 
> The important things to avoid are decrease in readability, and
> ioncreased difficulty in navigating them.

Readability will not decrease.  Navigability will *increase*, because
hotlinking between man pages will become routine.  

In fact, I deliver with doclifter a script called manlifter, This script
takes an entire manpage tree and transforms it into an equivalent HTML
tree *with crosslinks* -- all the foobar(n) references become hyperlinks.
 
> As to HTML/DocBook/SGML, it's pretty well established that they
> are valuable approaches to structured and cross-linked documentation.
> So anything which makes it easier to produce 'groff' documentation
> in these markups is welcome, so long as they do not interfere with
> the established merits of the documentation as it stands.

Neither the content nor the semantic layout of the groff man pages
will change in this scheme (there may be one minor exception, because
the DocBook DTD doesn't support multiple name-description lines, but I don't
know that any of the pages under discussion uses that facility).

> But groff at the same time began to display its strength as a
> general-purpose typesetting program, and it retains that strength
> to this day. Indeed, I'm prepared to argue that for many purposes
> it is as good as TeX and in some respects possibly better (though
> in others TeX does a better job); certainly when groff is used
> by skilled hands.

I *am* "skilled hands" in that sense, having done successful
full-length technical books in all three markups.  Speaking from
that experience, I rate groff better than TeX but inferior to a good
DocBook toolchain (with the exception that TeX wins over both if you have
to do really intensive mathematical typesetting).

Some progress does get made, and the modern paradigm of structural
markup plus stylesheets is superior to the presentation-level hackery
we grew up on.  And I say *that* as someone whose lingering fondness
for pic has attracted odd looks more than once! :-)

> Therefore my case for groff would not rest on man-pages. Indeed,
> if groff were superseded by something else for man-pages I would
> maintain that this would not diminsh the usefulness of groff,
> nor the necessity to keep it going.

I have no argument with you here, because I have no desire to kill
off groff -- in fact, I've probably done as much as anyone else has 
over the last ten years to keep it interesting.  My goal is, essentially, 
to move the corpus of content that now lives in man pages fully into 
the hypertext world.  This may imply that the historical connection
between man pages and [ntg]roff will lose its significance, but
that certainly won't kill groff.

(BTW, doclifter also lifts ms/mm/me documents.  About the only job
it doesn't do -- yet -- is translate eqn to MathML.  And that's in the
roadmap.)

> The classic structure of a man-page is lean flesh on a well
> proportioned skeleton. The art of man-page writing is to create
> that structure, embodying the information required in a clear
> and, above all, logical style (with careful logical links between
> related man-pages).

Agreed.  In fact, the result of my work may be to give that "art" a
new lease on life and a larger constituency.

> > But I think it's time to move on.  This little change will help
> > us get to a fully-hypertexted, Web-centric documentation corpus.
> > Let's do it.
> 
> So long, as I've argued above, as the basic structure is retained.

I hope I have allayed your nervousness on that score.
 
> > (And brace yourselves for the *real* political bunfight, which 
> > is when I try to kill off GNU info...)
> 
> You could have an ally ... !

Next year :-).
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>