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

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



On Wed, Apr 21, 2004 at 06:03:23PM +0200, Wouter Verhelst wrote:
> 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.

"On-line documentation" is not exclusive to manpages.  Let's drop the
use of "on-line documentation" entirely when comparing manpages to info
docs.  In fact, HOWTO's, books, and other classifications of
documentation CONTENT do not imply the MEDIA in which they are
distributed.

manpages SHOULD be concise and illustrative on how to use a given
application.  info DOCS contain documentation of the underlying
principles, verbose examples, and whatever musings the developer
desires.  Both are useful in their own right.  Both are forms of
"on-line documentation".

texinfo markup is a pain to use unless you use it a lot.  The same can
be said for many markup languages.  In the opinion of texinfo "people",
it is far easier to write in than nroff.  I don't mind taking an
existing manpage as a template and changing the content.  It's not
really that difficult.

IMHO, reStructuredText is the easier to use over either nroff or
texinfo.  Does that mean it's the Right Thing(tm) for Everything?  No.

Every tool has it's place.  Debian's mandate is that every application
requires a manpage.  It's a good mandate.  The Texinfo v.s. man (nroff)
argument has no place in this context.

-- 
Chad Walstrom <chewie@wookimus.net>           http://www.wookimus.net/
           assert(expired(knowledge)); /* core dump */

Attachment: signature.asc
Description: Digital signature


Reply to: