Re: [Groff] man pages (tangential to Future Redux)

[Eric S. Raymond]

Doug McIlroy <address@hidden>:
> Perhaps Gnu's most egregious contribution to Unix
> was to turn texinfo with its paleolithic interface
> into the "complete" documentation with man pages as
> stubs.

You will be pleased to hear, then, that RMS and I have been
discussing specifics of how and when to shoot this bad idea 
through the head.

Where we're probably going is that (a) info will die, to be replaced
by HTML browsed from within Emacs, and (b) Texinfo will be replaced by
a modern lightweight format that can render to both print and HTML;
most likely asciidoc.

While this won't directly solve the stub problem, it will at least
break the full documentation for GNU projects out of the ghetto they
have been living in onto the Web.  The functional win here is not so much
HTML's display capabilities as the fact that everything will be living
in the same URLspace.

Because the man-page stubs were a kludge to get around the complications of
browsing info outside of Emacs, I expect they'll quickly be perceived as
unnecessary after this transition and abolished in favor of Web pointers
to the real documentation.

This is as good a time as any for me to cop to the fact that writing
doclifter was only part of a longer-term plan.  I've been quietly
working for a decade towards moving man pages onto the Web and
dispensing with [nt]roff-based rendering entirely.  

Here are the elements of the plan:

1. Jawbone all the world's man page authors into cleaning up their
markup so doclifter can interpret it structurally to clean XML and
(through that) HTML.  I've been pretty successful at this: see
http://www.catb.org/~esr/doclifter/bugs.html for details and
statistics.

2. Some time ago I added to Linux man(1) the capability to recognize
HTML pages in the man hierachy and kick them over to the user's Web
browser.  All Linux and *BSD distributions now ship this code.

3. Kill off info.  See above.

Where I want us to be is that when users call man(1) the normal
behavior is to render through the browser.  As of now this *will*
happen correctly with only minor changes in how a distribution
installs manual pages, but nobody has flipped that policy switch yet.

I am patient about this; I'll begin advocating for it once I have all
the mechanism in place. Most of that's done now.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>