[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Texinfo vs man (was: Re: Debian GNU/Linux Reference Card under construction)



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


Reply to: