On Wed, Apr 21, 2004 at 05:30:28PM +0200, Jan Nieuwenhuizen wrote: > Wouter Verhelst writes: > > Additionally, info pages tend to be large, bloated, and full of > > unnecessary information > > Warning: religious issue detected. > > > (at least, information that IMO does not belong in on-line > > documentation) > > Now you got me wondering, what kind of documentation should be > prohibited from digital distribution, in your opinion? I never said that; I only said that good on-line documentation should concise and to-the-point information. Full, extensive documentation should be put in a HOWTO, a book, or on a website -- not in the primary on-line documentation tool. > > Not to mention the fact that Debian Policy mandates software to feature > > manpages, which cannot be said about info. > > Good point. How about fixing that requirement? How about let's not? This requirement allows a user to log on to a system, type "man foo", and get documentation; such consistency is good. Since there's much more software that has manpages but no texinfo documentation than the other way around, it's far easier to require manpages than it is to require texinfo. > > Especially GNU software seems to be horrible in this regard. > > You're trolling, but just to be sure, you do know why GNU deprecated > `man' about 15 years ago? Well, no. The only reference as to why that I could find is this paragraph from the GNU coding standards: ``Don't use Unix man pages as a model for how to write GNU documentation; most of them are terse, badly structured, and give inadequate explanation of the underlying concepts. (There are, of course, some exceptions.) Also, Unix man pages use a particular format which is different from what we use in GNU manuals.'' (section 6.1, at http://www.gnu.org/prep/standards_33.html) If you have more information, I'm happy to learn about it; but let me start off by disagreeing with the stance that being "terse" or giving "inadequate explanation of the underlying concepts" is necessarily a problem. As I said, IMO on-line documentation should contain concise and to the point information; underlying concepts, if they're complex, and other blatter, are for HOWTO's and books (either digitally or printed). -- EARTH smog | bricks AIR -- mud -- FIRE soda water | tequila WATER -- with thanks to fortune
Attachment:
signature.asc
Description: Digital signature