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 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]