Re: (Getting rid of) man pages

[craig at jcb-sc dot com]

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