From mboxrd@z Thu Jan 1 00:00:00 1970 From: craig@jcb-sc.com To: rich-paul@rich-paul.net Cc: craig@jcb-sc.com Subject: Re: (Getting rid of) man pages Date: Fri, 30 Apr 1999 23:15:00 -0000 Message-ID: <19990424124335.14954.qmail@deer> References: X-SW-Source: 1999-04n/msg00847.html Message-ID: <19990430231500.lfI9n1diBaITZ16rK3zG3klt7VrUFP57D4mgmG7kj-4@z> >Just to put in my two cents, 'invoking gcc' very nice for what it is, but >it ain't no man page. One of the great things about man pages is that >they have a very specific set of sections, normally in the same order. > >Near the top, they have a canonical list of flags, so that when you find >some invocation you don't grok in some makefile somewhere, you have a hope >of finding a clue. It won't tell you all the whys and wherefores, but it >will give you just a QUICK idea of what the damn thing does. I've been seeing the same pro-man-page arguments for *years*, and have yet to see anyone, or any group, step forward and *volunteer* to maintain them for GNU to any serious extent. Without getting into a debate -- because, frankly, I've got too much expertise to be interested in having people here try to convince me why I should prefer maintaining, or even reading, man pages, especially given the inarticulate arguments I've seen in their favor to date -- let me say why *I* prefer to maintain docs in GNU Texinfo format over those in man format: - I've been reading computer documentation for 30 years now, and haven't seen many formats as annoying to read as typical man pages. They simply are *not* well-designed for on-line reading, though I gather they're better when printed out (they looked better when I've seen them printed in the distant past, though the printed forms of Texinfo I've seen most recently were superior in most respects). - When I've worked as a tech-writer, the more "man-like" (nroff) the input language I was dealing with, the more unmaintainable the documentation in its source form. *Period*. (Not that Texinfo, the makeinfo program, and so on can't be improved -- but they don't need *overhauls* to be usable.) I've had better experiences maintaining documentation in plain text (which is why I've gone from that directly to Texinfo in my g77 work, not even bothering with man pages for anything but a bare-bones one, copied from g++'s long ago to make it "easy"). - GNU Texinfo format is simply superior. It's higher-level, it's more device-independent, and it's got real hyperlinks, which work fine as static-form references. (That means I don't, as a reader *or* author, have to balance repeating information against doing *painful* cross-references.) - Every improvement I've heard of, or can *think* of, that could be made to typical Texinfo (I see them mostly as Info) documents to make them better meet peoples' man-page-based expectations could be *better* made to Texinfo and/or to Info or HTML readers (and there *has* been progress made here, over the years) than made by switching back to man pages. So, whenever I hear people say "I'd rather you maintain your docs as man pages than Texinfo/Info", it sounds pretty much the same to me as when they say: "That C language you're writing your code in is *so* hard to read. I'm used to reading assembler. Could you please maintain your code in assembler instead, or at least in parallel, so it would be easier for me to read?" Put simply, *I'm* going to say "no". *Always*. Even though, in both cases, I agree there are situations where the lower-level-language version *is* easier to read for certain kinds of uses, I'll always lean towards making a bigger investment in improving my C code, the C language, and C compilers, than would be needed to get some improvement in maintaining a *particular* version of my code in assembler -- because I'm (as always) looking at the *long-term* costs of maintenance. But, if a bunch of you want to get together and form the "GNU man-page project", to meet and prioritize which GNU man pages you think are most important to write (we've, e.g. the g77 man pages, have been calling for volunteers to do that for *years*), by all means, go to it. I'd suggest you figure out what *conceptual* information you really want, first; how to best architect that into the present *Texinfo* document (not just what new @-style markup you might need, but how typical GNU Texinfo docs could be better architected overall); then perhaps how to mark it up in a canonical way so automatic extraction tools can convert the Texinfo to man pages, at which point you can collaborate on providing such a tool. There's already @ifhtml/@end ifhtml, as well as @ifinfo, etc. A @ifman might be appropriate, but I'd hope that, if you did your homework properly, higher-level constructs would be more suitable. (If man pages were important to *me*, I'd have done the above as of about three years ago. If you want to hire me as a consultant to do some of the work, I'm *definitely* open to that, and have plenty of expertise across the spectrum, having architected, designed, and built documentation systems, including indexing tools for tech writers, in the past. That I don't see it as anywhere near important enough for me to spend my *volunteer* time doing it does not mean I'd give such a project short shrift!) But please, *please*, stop pestering any of the various GNU development lists with these discussions any further. Get your *own* list, invite people onto it, set up a web page (call it "The GNU Needs A Real Man Page" or something clever ;-), announce it on gnu.announce, whatever. Realize that any solution to this problem is, IMO, going to involve GNU developers like myself *only* to the extent that it constitutes high-level improvements to how we write *Texinfo* (and therefore our Info, HTML, DVI-printed, etc.) documentation. That's because most of us recognize that maintaining *two* forms of documentation is a *lose*, and that, at least for now, Texinfo is pretty much our #1 choice, when looking at all the factors, while man-page (nroff) format is probably not even in the top 5 or 10. And if you want to get an idea of how much better a use we could make of *Texinfo* format than we already do today, try compiling this line as file "foo.f" via g77 -- "99999 %invalid token" -- and "follow" the link given, using either "info -f", or Emacs Info mode's "m" command (first look for "M", then "LEX", as directed). Then ask yourself, how would that much documentation on a *diagnostic* be fit appropriately into the man-page system you love so much, how would it be dynamically hyperlinked-to, how well (vs. Texinfo) does it "scale up" to real end-user systems like the various windowing free-software GUIs people are designing (for Linux, for example), how well (vs. Texinfo) is it prepared for improvements for internationalization, etc.? I mean, I think *Texinfo*, and the GNU documentation written in it, has a long race to run, to be really great, and I haven't convinced myself (yet) that they'll even be able to *finish* -- that a whole new paradigm won't be needed down the road, one that is to Texinfo what Texinfo is to man pages. But, from what I've seen, man pages aren't even in the *race* -- they're sitting on the couch, watching it on TV, recalling their glory days. Give me a pointer to a web page to convince me (and the GNU people who make the high-level decisions about this) otherwise, if you like. In the meantime, stop pestering GNU development mailing-lists with this issue. It's just *so* annoying hearing the same tired old arguments over and over again, on a forum where we're supposed to be getting work done. tq vm, (burley)