[Groff] RE: Simplifying groff documentation

[Ted Harding]

I'll respond (in general sympathetically) to various points
in Eric Raymond's "manifesto". Most of the rest is snipped.

On 22-Dec-06 Eric S. Raymond wrote:
> Werner LEMBERG <address@hidden>: 
>> > Who is the person currently responsible for groff?  Is it still you?
>> 
>> Yep.  Awaiting your commands.
> 
> So I see from the groff project page, which I should have checked
> first.  Copying to Ted Harding and the groff list, which I just
> subscribed to.
> 
> I want to drastically simplify the markup used in several pieces of
> groff documentation, eliminating a lot of the hairy custom macros they
> presently use.
> 
> groffer.1
> groff_out.5
> groff_tmac.5
> groff.7.gz
> groff_char.7
> groff_mdoc.7
> groff_trace.7

As part of a new spproach to 'man' markup, and given the remarks
about idiosyncracies of groff-specific markup, there could well
be a case for this!

> The hardest format to webify in the Unix world is also the most
> important one -- man pages. (By way of GNUish contrast, TeXinfo is
> much easier.)  There are a large number of tools that attempt this
> out there.  In general, they do a crappy job.

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.

> Thus, groff is my second largest source of man pages that can't
> be lifted to DocBook. The largest is netpbm, and I'm working
> with its maintainer to fix that now.  
> 
> So this is the answer to "why fix it?".  Because the groff pages 
> presently do elaborate, bizarre things that doclifter can't cope
> with. In this they are *unique*.  I mean *unique*.  Everywhere
> else the problem is almost entirely broken markup, not things
> people did deliberately.
> 
> 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.

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.

> 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?

Here's where I possibly join the bunfight. One might argue that
making 'man' depend on groff is indeed a historical legacy, though
I wouldn't in fact go along with that.

It's certainly true that Unix documentation historically depends
on groff, in that groff was invented first (for other purposes,
one of which was to save the life of Unix!). Once it existed,
of course, it was a logical and frutiful road to pursue, in
producing Unix documentation in the form of man-pages--and also
of course in the form of printed manuals.

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.

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.

On the other hand, there is a "mind-set" amongst some that the
purpose of groff is to format man-pages, and to such people a
change to something else for man-pages could mean that there was
no longer any case for groff in a Linux/Unix distribution (except
for those weirdos who really want it).

I'm personally not that interested in "groff for man-pages" as
such (though I think that it's as good as anything else so it
might as well be used), in that I would not favour the intrinsic
functionality of groff being vulnerable to the demands of man-page
formatting. Let groff develop as a real typesetting engine in its
own right, for the production of documents of all kinds, and let
'man' take what it can from what groff has to offer.

> I don't ask this question dismissively.  I probably grok *roff
> hackery as well as anybody who isn't Brian Kernighan -- groff
> carries two tools I wrote (pic2graph and eqn2graph) and I wrote
> your guide to pic.  I think man macros will still have a place
> as a composition format, even if nobody presents from them any
> more.

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). The groff markup for this need not, in my
view, be overly sophisticated. 

> 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.

> (And brace yourselves for the *real* political bunfight, which 
> is when I try to kill off GNU info...)

You could have an ally ... !

Best wishes,
Ted.

--------------------------------------------------------------------
E-Mail: (Ted Harding) <address@hidden>
Fax-to-email: +44 (0)870 094 0861
Date: 23-Dec-06                                       Time: 00:48:51
------------------------------ XFMail ------------------------------