🚀 go-pugleaf

Documentation _is_ relevant to C, so

>Matthew Sams <maclean@CS.McGill.CA> writes:
>> Personally I find the info system much better than the man system
>> for long complex documents. Can you imagine the emacs lisp manual in
>> man page format? eek.

I am in full agreement with this, BUT it mistakes the purpose of UNIX
man pages.  A man page is supposed to be A PAGE, or at best only a few
pages.  In essence, they are supposed to be on-line quick reference
cards.  man pages and TeXinfo documents simply do different things.

When I want to find out how to use gcc to generate makefile dependencies,
all I want is the "quick reference" so that I can find out how to spell
-MM and whether it has one M or two.  I don't _want_ a long tutorial.

When I want to find out all about the gcc language extensions, I don't
want the quick reference.  THEN I want a long tutorial.

As an experienced AWK programmer, if I want to check on the functions
provided by gawk, I want the "quick reference" that lists their names
and *briefly* describes their functions, so that I can check if the
one I already know about and want is there.  If a student wants to
learn all about regular expression pattern matching and to see some
examples, then she wants to read the long tutorial.

In short, NEITHER kind of document can replace the other, because they
serve completely different needs.

jeffno@annapurna.ccs.neu.edu (Jeffrey Nowakowski) writes:

>Getting way off topic here, but such is Usenet.  If GNU wants to call
>man pages obsolete, then they should trash Info too and switch to
>HTML, which is a lot more powerful and easier to use.

The UNIX manuals use nroff instead of LaTeX and Emacs because they 
existed before LaTeX and Emacs did.
The GNU Info documents use LaTeX and Emacs instead of HTML because
they existed before HTML did.
TeXinfo files also do important things that HTML does not do, like
numbering sections, generating tables of contents, and indexes.


For C programmers, I note that there is a program called 'c2man'.
From the README file, c2man is 

    ... a program for generating Unix style manual pages in nroff/troff
    -man, TeXinfo, LaTeX or HTML format directly from ordinary comments
    embedded in C source code.  It should run on virtually any Unix-like
    system, OS/2, VMS, MSDOS or Amiga systems.

The current release is version 2 patchlevel 40.  With such a tool
around, if you are writing a library of functions, there is no longer
any good reason NOT to produce documentation.  The hardest part about
writing UNIX manual pages was learning how to use nroff, which is, um,
arcane.  c2man does that bit for you.  You just have to provide the
content.  And if you want both man pages and TeXinfo, you can get them
_automatically_; best of both worlds.

-- 
The election is over, and Australia lost; the idjits elected _politicians_!
Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.