man or Info? Both!! [was: problems with pow( ) in gcc]

["Stephen J. Turnbull" <turnbull@example.com>]

>>>>> "sb" == SL Baur <steve@example.com> writes:

    sb> In this case, the synopsis is wrong.

You mean wrong as in "incomplete"?

    sb>      cc [ flag ... ] file ...  -lm [ library ... ]

Missing the above, I guess?
________________________________________________________________________

    sb> Info is just another Stallman NIHism.

Raaaaaaight.  C'mon, Steve, what did he do to you today?

    sb> Man pages have worked fine for decades

Man would not be man if you made it into a hierarchical format.  Man
is a flat database, random access to precisely specified information.
Perfect (if the man page were correct) for the problem that started
this thread.  Abominable for humans looking for underspecified facts.
man -k is just not suited to anyone below the level "Wizard".  Done a
ls /usr/share/man/man3 lately?  No, thanks!

Man is not suitable for textbooks or overviews as extensions of the
manual.  (Read the X(7) man page recently?  Gag, puke, barf.  But I
don't think I could write it better in man page form. :( ) Info (and
to some extent HTML[1]) are.

Lispref in man page format?  I don't think so.  (But I admit it would
beat the CL HyperSpec with a stick, what a piece of unnavigable crap!)

    sb> and too many recent software packages are ignoring it to the
    sb> detriment of everyone.  Shame on GNU and shame on KDE/Gnome
    sb> HTML help.

No question about that!

The "GNU doesn't have time to update man pages" statement translates
to "GNU doesn't give two shits about quality."  If you can't write a
man page, you shouldn't have commit privileges, 'cause you don't have
any idea what your code does.  (And they should take your Emacs and vi
away, too.  "Plastic cutlery for you, Baby Sweetums, no sharp tools.")

If you _can_ write a man page, then Info can be used to provide links
to it (man is not at all a bad format for Info leaves and function
docstrings) and text/tutorial/overview material.  Info should allow
the man pages to do what they do better than any other documentation
form: provide essential syntactic information in a couple of 24x80
screens.  But Info is better suited to complex semantics.

It does crack me up that the bash man page is _still_ easier to
navigate than the bash Info docs.  "Bash-specific features" in the
top-level menu -- who thought _that_ crock up?  I wouldn't be
surprised if the man page is still more complete, too.  :-)

Footnotes: 
[1]  The HTML DTD is not suited to Info-style navigation.  You should
not have to move the cursor to follow an xref.  And there is no excuse
whatsoever for <FONT> and <SIZE> tags in documentation.  HTML
authoring tools invite authors to do just about everything wrong.

-- 
University of Tsukuba                Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
Institute of Policy and Planning Sciences       Tel/fax: +81 (298) 53-5091
_________________  _________________  _________________  _________________
What are those straight lines for?  "XEmacs rules."