Re: [Groff] ESR in manpages versus the WEB

[Gunnar Ritter]

mhobgood <address@hidden> wrote:

> >  It's the 21st century, all the documentation on my system ought to  
> > present as a hypertexted local Web through my browser.
>
> Subject two.  That is your personal preference.  Myself, I'm quite  
> happy to use other forms for documentation; forms that do not invoke  
> my browser at all.

The real argument for DocBook is that such a document can
be converted to any presentation format with relative ease,
regardless of personal preferences. Thus if you say that
Eric prefers a web browser but others might prefer other
viewers, you should rather argue for doclifter, not against
it.

Besides, it is completely clear that Eric is not the only
one who wants this. Desktop environments have tried to offer
similar services since years. You have simply misunderstood
the personalized formulation of Eric's argument.

> > 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.
>
> Subject one.  Question: what constitutes a crappy job?

This is simple. It really suffices to try the existing
tools to find it out. I would not go as far as to call
them "crappy" - as I said, I am mostly satisfied with
one of them in practice - but it is really easy to see
their serious limitations.

> But,  
> if a manpage does elaborate, bizarre things, it is your program that  
> must cope.

You are the first person I have met so far who thinks
so. All guides to manual page writing I have read also
disagree with you.

Maybe you could just rethink your opinion?

> D.E. Evans asked about an improved grohtml, or even a replacement.   
> Perhaps grohtml can be improved.

grohtml is broken by concept. It is thus impossible that
it will ever reach a satisfying state.

troff is fundamentally a tool that translates a document
in a visual markup language into a document in a page
description language. That is, it accepts out-of-context
instructions for fonts and point sizes etc., applies
page-, paragraph-, and word-level formatting (H&J) and
generates code that specifies the exact location of all
glyphs on every fixed output page.

HTML, in contrast, operates at a higher level than even
troff input does. It would thus principally make sense to
translate HTML documents into troff input, although there
seems no demand for doing so.

But the reverse direction does not make sense. It throws
away the main work of troff (pages, H&J) but adds code for
structural markup which troff does not normally even know
about. (Yes, I have seen the hacks to change that.)

The concept of doclifter makes much more sense. Since it
accepts input written for a macro set that is not too far
away from structural markup, it can generate output in a
language at an even higher level than HTML.

But this can only work for manual pages that do not have
too much raw troff code in them. Otherwise, the job of
doclifter quickly becomes as impossible as that of grohtml.

Note that this is not just because troff input is difficult
to parse. Even if a program can parse it completely and is
able to evaluate the most complicated expressions, it still
cannot distinguish between a centered heading and other
centered text unless the heading is explicitly marked as
such. All it can do is to render it as specified, and
grohtml cannot even do that because HTML is an not an
appropriate language for that task.

Ultimately, your argumentation is just a demonstration of
your lack of knowledge about markup language concepts. You
have asked us to "explain what XSL and FO are" a week ago;
perhaps you might consider to familiarize yourself with the
subject in more depth now before you continue to discuss in
that style?

        Gunnar