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

[James K. Lowden]

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?  

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.  

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.  

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.  

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.  And
still you can't draw a picture.  

Compared to a lot of people on this list, I'm a newtimer.  I arrived at
groff having resisted at every turn.  I wrote HTML, CSS, DocBook.  I
used txt2man to avoid learning mdoc.  Then one afternoon after I
couldn't get it to do what I wanted, I sat down an converted the whole
set (about 10 pages) to mdoc.  It wasn't so hard once I got over the
prejudice that it looked like Wordstar.  

What I discovered, in other words, is that in troff the writer
asymptotically approaches its capability.  The "simpler" the system, by
contrast, the more likely he will exponentially approach its
limitations.  

--jkl