Re: [Groff] Effective manpages, a couple of thoughts

[Jorgen Grahn]

On Fri May  7 15:03:37 2004, address@hidden wrote:
...
> What do you think about the idea of having *both* a
> long and a short manpage for a complex subject, where 
> each references the other? In other words, one is
> short, the other is complete. :-) My thoughts are
> that someone new to the program (or *nix in general)
> could use the short version to find the basic info
> needed, and experienced users could access the long 
> (default) version to get the entire scoop.

We spent a pretty long thread to discuss length vs. completeness, but what
disturbed me about the original paper was actually the idea to mechanically
leave out stuff from the nroffed output and only include it in the typeset
version.

Maybe it's just me and my background, but one important aspect of man pages
is that the man page is The manpage.  One tool - one manpage, which looks
the same onscreen or printed.  I think I even prefer an incomplete manpage
plus info documentation, compared to two similarly-named manpages with
different detail level.

But the optimal situation, of course, is when the thing described so simple
that it only needs one smallish manpage.  Because I agree with Meg -- as
soon as it's not in the manpage, chances are that the user will never bother
to find and read it.  I know /I/ work that way.

By the way: I hope we're discussing pretty rare cases here. All of the
things /I/ write are small tools which only need a small manpage. That's
where manpages really shine - they are so easy to write that you can always
take the time to do it, they are trivial to install, and they're trivial for
the user to bring up.  In the non-civilized world, the best documentation
you can hope for for such a tool is the help output, or a README file
containing some random notes, which /maybe/ has been installed to
somewhere ...

BR,
/Jörgen

-- 
  // Jörgen Grahn       "And then the design was ignored, and small children
\X/ <address@hidden>  with crayons were given the O'Reilly Perl books and
                         told to Create.  And lo, it was done."
                                                         -- Teo de H, in ASR