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? 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
