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

[Jorgen Grahn]

On Mon Apr 26 22:32:09 2004, address@hidden wrote:
> I've started a short document on writing what I call "effective" 
> manpages -- readable and useable with a variety of output formats. I 
> hope it will eventually become source material for other groff 
> documentation (like my "ms" reference) or UTP Revisited.
> 
> HTML version: http://home.alltel.net/kollar/effman.html
> Source (ms+www): http://home.alltel.net/kollar/effman.tar.gz
> 
> Comments and further tips are welcome. :-)

I'll bite:

the title

- I think the material is still a bit narrow to warrant the title -- surely
  there is much more than this to writing effective manpages?

ch 1.1

- I disagree with the two pages limit for nroffed manpages, There /is/ a
  limit though (and bash(1) is way past it!)

- Do we /really/ have to cater to applications like xman which try to format
  manpages without a real troff? Who uses xman these days?
  (And then I see the reference to Konqueror in ch 2.2. *sigh* Why couldn't
  they just steal from xditview or something?)

ch 2.1

- foo(1), foo(5) and foo(7) may be better first examples that mysh(1) and
  mysh_prog(1). I'd hate to see people start using homemade suffixes in
  cases where they could use the standard man sections.

ch 4

- Omitting parts of the documentation if nroffed seems to be a bad idea. To
  me, a manpage should be short and (WRT the kind of material it covers)
  complete. If it's not viewable onscreen, it's not a manpage.
  
  What you suggest is a "Reader's Digest" nroffed version plus, since people
  know how to invoke man but not how to invoke troff, a full PostScript or
  PDF version installed under e.g. /usr/doc/<packagename>. But is this
  latter thing really the manpage? Shouldn't it be "the full documentation",
  formatted with e.g. -ms and not following the usual manpage structure with
  'synopsis', 'see also' etc?

  For reference, Eric Raymond has this to say, in
  http://www.catb.org/~esr/writings/taoup/html/ch18s06.html
  
    Huge man pages are viewed with some disfavor; navigation within them can
    be difficult. If yours are getting large, consider writing a reference
    manual, with the man page(s) giving a quick summary, pointers into the
    reference manual, and details of how the program(s) are invoked.

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