Re: Info vs Man
On Wed, Feb 11, 2004 at 13:10:51 -0600, Kent West wrote:
> At the risk of starting holy war, why has the GNU project decided to go
> with info pages instead of man pages?
> Some of the other hits seemed to imply that man pages were better,
> although there was no definitive explanation as to why (or why not).
>
> Anyone have any insight on this question?
The man format is a suitable format for reference documentation of software
that isn't too complex. If a manpage is larger that say 15 to 20 physical
pages, the lack of structure (or if you will, the rigidity of the sequential
section structure) becomes annoying for readers.
The GNU info format is a hypertext format; it allows documentation to have
more structure, both hierarchical (sections, chapters, appendices etc.) and
non-hierarchical (cross-references, footnotes). This allows it to be an
acceptable format for larger pieces of documentation, such as documentation
of more complex programs or applications and for tutorial documentation.
Take the GNU C library as an example. It ships with extensive documentation
in info format; last time I checked corresponding to over 750 A4 pages. Now
imagine all that information in a manpage, and having to use a regular pager
to find stuff in it...
The GNU C library is also documented through manpages (from the Linux
manpages project). Those are short, to the point, and are good for reference
purposes. They're useless if you want to learn what the C library can do for
you, but they're great if you're just looking up what header file provides
the function you want to use.
> If I were to write up some documentation for some application, would I
> want to create it as a man page, or an info page, or as both, or as some
> higher(/lower)-level format that then gets converted (by me/by viewer
> tools?), what?
I'd say that depends on the type of documentation you want to create
(tutorial or reference) and on the level of formatting control you feel you
need to exert.
If you're not a format control freak, a format like DocBook XML or SGML may
well be what you want: a high-level, easy to create and easy to read as
source format that can be converted to lots of things (DVI, PDF, PS, plain
text, HTML + stylesheets, RTF and manpages). If you consider lazyness a
virtue, perl's POD (Plain Old Documentation) is a very easy to learn format
that can be converted to acceptible manpages, HTML, plain text or
DVI/PS/PDF.
If you are a format control freak, the best format to write manpages in is
directly in *roff and the best format to generate info from is TeXinfo.
HTH,
Ray
--
AJ: Geeez, Erwin. He wasn't even ARMED.
Erwin: I don't care. I have lots of ammo and he was wearing a TIE.
http://ars.userfriendly.org/cartoons/?id=20010209
Reply to: