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