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

[Eric S. Raymond]

James K. Lowden <address@hidden>:
> On Sat, 1 Mar 2014 07:55:08 -0500
> "Eric S. Raymond" <address@hidden> wrote:
> 
> > What we have now in the Linux/Unix documentation world is a large
> > pre-hypertext pile of documents with no link structure (manual pages) 
> > and a smaller, weirder one (info) with a sort-of half-assed link
> > structure. My goal is to level the walls around both and merge them
> > into the Web.
> 
> Hmm, so SEE ALSO is not a link structure?  Because it's semantic markup
> without tools to, er, render the link structure operable?  

Yes, that is a problem - which doclifter directly addresses.  It's fairly
easy to supply hints that will cause SEE ALSO references to be turned
into working links to other HTML pages under /usr/man.
 
> I think I understand your affection for HTML.  The browser exists and
> functions, and continues to be actively developed.  If all
> documentation were in the browser, it could be cross-referenced and
> viewed wherever a browser is available.  I'd like something better, and
> I bet you would, too, but it's what we have.  

That last sentence captures my attitude exactly.

Perhaps a more precise way to put it is that HTML is minimally good
enough, and doing *better* than HTML would require an infeasibly
complicated reinvent-the-world project.

> I don't share your enthusiasm for the browser.  I find the browser
> an inconvenient UI.  I particularly dislike the DocBook-inspired
> page-per-section style, where I have to click on the "next page" link
> for practically every paragraph.  

I agree. But that's a stylesheet choice, not anything intrinsic about 
DocBook or browsers.

> Back in the terminal, while I wish for a better viewer than less(1), I
> rely on its search capability -- which, unlike most browsers uses
> regular expressions -- to find sections or things I vaguely remember.
> The bash reference manual thankfully reverted to a simple manpage a few
> years back; now "/:-" immediately jumps to parameter expansion, and
> "/^FILE" jumps to the configuration files.  

We already have one browser that does regexp search on the page.  Emacs.

> I can't fathom asciidoc as a standard.  It's demonstrably less
> expressive than mdoc (or DocBook).  Once you get past a few simple
> things -- titles, lists, bold and italic -- the metacharacter strings
> build up and become just as arbitrary and weird as anything else.

All these criticisms are fair.  Speaking as a heavy user of both, I
would never try producing a full book in asciidoc.  But it is *very*
well matched to the requirements of man pages, FAQs, and long-form 
technical documentation.

> And still you can't draw a picture.  

Actually, you can.  It takes some cleverness with passthrough
constructs, though; the markup youd use isn't part of asciidoc itself.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>