James K. Lowden <jklow...@schemamania.org>:
> On Sat, 1 Mar 2014 07:55:08 -0500
> "Eric S. Raymond" <e...@thyrsus.com> 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>
