Re: [groff] groff as the basis for comprehensive documentation?

[James K. Lowden]

On Mon, 16 Apr 2018 13:19:31 -0500
Nate Bargmann <address@hidden> wrote:

> I'm still undecided on the Texinfo part, though it may serve as the
> portion that ties everything together.  I have man pages for utility
> programs of the project and will be writing man pages for the C
> library.  Being able to collate this nicely would be a great
> benefit.  

I went down your very same road some years ago, except I used jade and
SGML instead of XML for DocBook.  I found LaTex too confining and
complex.  Once I bothered to learn mdoc, I wished I'd started there.  

The roff language is the only markup language in current use that was

        1.  designed to be typed by humans, and 
        2.  designed to produce typeset documentation.  

I think there was hope, once upon a time, that a free implementation of
something like Interleaf would become the UI for DocBook, and that mere
mortals wouldn't have to balance their tags.  Needless to say, it never
came to pass.  Lyx isn't it.  

The design of the roff language, while not "modern", is minimalistic;
it has the least markup as a percentage of text.  It makes few
assumptions about how the text should appear, and those assumption are
well documented and easily adjusted.  The groff implementation is fast
and small.  As Hoare said of Algol, it is an improvement over its
successors.  

The full current capability of groff is harder to exploit than it could
be, however.  There's still a bias toward printed output.  To create a
document like Deri's, with hyperlinks, you have to understand the
system pretty well, and piece together a few documents, some of which
are incomplete.  Cross references in mdoc, for example, do not generate
links in HTML or PDF documents.  It's possible to produce presentation
slides, too, but you have to do a little digging.  

> Ideally, if the same sort of collation could be done with HTML, that
> would be perfect.

Groff is not the ideal system for generating HTML.  You might like to
believe that eqn, tbl, and pic could be processed with grohtml and come
out lovely on the other side, but that goal remains over the horizon.
It's pretty rare just to find manpages rendered in proportional HTML
fonts.  

--jkl