Re: [Groff] Draft paper: "Writing Effective Manual Pages"

[Jon Snader]

On Tue, May 04, 2004 at 08:15:58PM +0200, Tadziu Hoffmann wrote:
> 
> > Most seem to agree that the bash manpage is too big
> 
> I for one would like to disagree (and somewhat reduce that "most").
> 
> The manpages are a *reference* manual, and *have* to include
> all that's relevant.  Complex and intricate programs with
> many functions and options need longer manual pages.  Period.
> If the bash manual page were made any shorter by leaving
> something out, it may become completely useless, because the
> next time I accessed the reference, perhaps exactly that bit
> of information was what I needed/wanted to know.  I would
> hate to see a reference split up into "manual for dummies"
> and "manual for experts".
> 
> The bash manual page *is* concise, as you would expect for
> a reference.  It is neither a tutorial nor a philosophical
> treatise on the whys and wherefores.  (This is currently
> the domain of the info pages -- not ruling out that these
> cannot be just as well be presented in manpage format.
> Question:  What's the best way to read info pages?
> Answer: info foo | less.  The search capabilities of less
> are so useful that you can easily do without all that
> navigational gimmick.)
> 

I reluctantly must agree with this.  As annoying as long man
pages are, they're preferable to omitting vital information or,
worse yet, the odious Perl practice of making every single
function a separate man page.

We may be overworking this issue.  The point of Larry's paper is
to lay out some guidelines for making man pages useful, not to
serve as draft legislation.  If we all keep our man pages as
short as possible while covering the required material, we will,
in general, limit most man pages to a MANagable 8-) length.  Some
cases, such as bash, just have to be exceptions.

As others have said, the info system is a non-starter for me.

jcs