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

[Pete Phillips]

>>>>> "Larry" == Larry Kollar <address@hidden> writes:

    Larry> Most seem to agree that the bash
    Larry> manpage is too big, so we at least have a consensus between 3
    Larry> and 57 pages.  

Well I disagree I'm afraid. Perhaps the advice should be, "keep it as
short as possible, but as long as necessary" :-)

    Larry> First, there's the concept of short-term, or "working"
    Larry> memory, as described at
    Larry> http://www.psych.ualberta.ca/~mike/Pearl_Street/Dictionary/contents/
    Larry> S/short_term_memory.html

I personally don't think this is relevant. When we took delivery of a
UNIX System 5.1 system (CTIX), yes - I took the manuals home and
devoured them all.  That's how I learnt UNIX. But not today (hey - I've
got a life you know!).

Today I rarely read a man page from start to finish. I see it more of an
information repository. Yes - it is good to have it in a recognisable
format (for example, the See Also section at the end means I can go
there with 'G' in less), but in general this is how I use man pages
(your mileage ........):

1 - what does command xxx do:

  man xxx; scan the first few lines - usually enough to tell me.

2 - how do I do X; 

  for example, a few weeks ago I wanted to run the 'series' command
  inside a shell script, but didn't have Gary Perlmans STAT|
  package installed on my laptop. I knew zsh could to arithmetic, so...


  man zshall; 
  Use less' search:  /ARITHMETIC

  a few 'n's later and there it is - a loop that I can use to generate a
  series
          for (( f = 0; f < 101; f += 1 )); do

3 - I'm really interested in learning more about zsh  - and I've got a
        free evening !

        man zsh | a2ps

        wait for the dead tree to arrive in the printer tray, stick it
        in my rucksack and think up lsome plausible excuse to explain to
        my wife why the front wheels of the car are lifting like a
        dragster.....

4 - Hmmm - which command can I use to convert an eps file to pdf ?

      man -k eps

    Ahh - eps2pdf  (yeah - I know - most of us would have typed 'eps'
    then command completion, but ....)

      man epstopdf
 
    and read the Synopsis.

5 - I seem to recall a groff variable which allows you to add a local
    tmac directory:

     find /usr/share/man -type f | xargs zgrep TMAC

   ahh yes - GROFF_TMAC_PATH


In most of these scenarios, what is important is that there is a *single
centre* that I can turn to. I hate it when I draw a blank in the man
page, then have to look at info files, then in /usr/share/doc.

I come back to what I said earlier on - "as short as possible, but as
long as necessary" - OK - no tutorial on 'ls' and no philosophical
discussion about the number of switches that are necessary, but
certainly everything I would need to know, including some example
code/usage, all ENV variables, switches. That means some man pages are
going to be *very* long, but I see that as a good thing - they end up
being a reliable central information repository.

    Larry> But none of that makes manpages irrelevant. To put it
    Larry> bluntly, there is no other format out there that is both
    Larry> widespread and allows both console viewing and printing from
    Larry> the same file.  

and add *searching* to that list.

I totally agree with your other comments, but I'm really entering a
plea to avoid an arbitary limit on man pages.

Pete