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

[Clarke Echols]

When I was in charge of the man pages at HP, I **ALWAYS** set all
literals (command names, hyphens, etc.) in Courier and at one point
smaller than the New Century Schoolbook used for regular text (much
more readable than Times and looked nicer too).  Variables were
always in italics.

Worked like a charm, and hyphens never ran together.

It stirred up a real ruckus when I abandoned bold for literals
and didn't start a sentence with an uppercase letter if the first
word was a literal.  I also got rid of the uppercase page names
at the top in the heading.  The AT&T purists objected, but their
fight was short-lived.  I won because management accepted my
judgment.

Thus the header was "cp(1)   ...   cp(1)" instead of CP(1)...CP(1)
and the first word in the DESCRIPTION was "cp copies..." with cp
in Courier.

I changed the entire source-file coding with a shell script that
ran vi non-interactively from a command script file.  For the stuff
vi couldn't do, I ran the contents of the file being edited to sed
for further changes.

It worked like a charm.  Completely overhauled the entire 1500 printed
pages in a few minutes on a computer running a 30 MHz processor in
1989.  It took less than 3 or 4 hours to write and debug the scripts.
It also converted \fB, \fI, etc. into macros .BR, .B, .BC ("C" for
Courier or "code"), .CI, .IC, etc. and made a much cleaner package of
source files that looked like they all came from the same shop.

Once the product was out the door, everyone was happy.

I also wrote a template file that was a man page titled "How to write
man pages" that engineers could use to create new pages.  That also
worked well and was quite popular.

Clarke

(Ted Harding) wrote:
> On 09-Aug-09 11:46:06, Ralph Corderoy wrote:
> > Hi,
> > Pete Phillips wrote:
> > > 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
> > man(1) will produce nicely formatted PostScript for you, rather than
> > printing out a fixed-width version.
> >
> >     man -t bash | ps2pdf - bash.1.pdf
> >
> > BTW, does anyone else find the dashes used for options ugly in
> > bash.1.pdf, e.g. the `-c string' and the `--debugger'.
> >
> >     $ zcat /usr/share/man/man1/bash.1.gz | grep debugger | sed q
> >     .B \-\-debugger
> >
> > I think they should be using plain `-', i.e. as
> > http://plan9.bell-labs.com/sources/plan9/sys/man/1/troff does.
> >
> > Cheers,
> > Ralph.
>
> An interesting and distinctly moot point! I agree that the "\-"
> come out too close together in the PS output, and the effect is
> even worse in lines like
>
>   --dump-strings
>
> where the "-" between "dump" and "strings" really should come out
> as a true hyphen if set in Times.
>
> On the other hand, I do feel that the "-" or "--" which flags an
> option would look better if it were in the more conspicuous "\-"
> form. So, on that basis, "--dump-strings" should be sent to groff
> as "\-\-dump-strings". But this still has the defect that the "--"
> aqre too close together. At the magnification at which they would
> be printed, they are almost indistinguishable.
>
> However, I have no taste for getting tangled with the diktattery
> (GNU or other) about how man pages must be formatted! I can only
> say, speaking for myself, that if I were writing this kind of thing
> in Times, I would want to set things like command-line text in Courier
> Bold (and at a slightly reduced point size). Say something like
>
> \s-1\f[CB]--init-file \fP\f[CBI]file\fP\s0
> .br
> \s-1\f[CB]--rcfile \fP\f[CBI]file\fP\s0
> .IP \"If using ms macros
> Execute commands from \s-1\f[CBI]file\fP\s0 instead of the system
> wide initialization file
> \s-1\f[CBI]/etc/bash.bashrc\fP\s0
> and the standard personal initialization file
> \s-1\f[CBI]~/.bashrc\fP\s0
> if the shell is interactive (see \fBINVOCATION\fP below).
>
> I think this looks much better -- and is more readily interpreted
> by the reader, which is important!
>
> Ted.
>
> --------------------------------------------------------------------
> E-Mail: (Ted Harding) <address@hidden>
> Fax-to-email: +44 (0)870 094 0861
> Date: 09-Aug-09                                       Time: 13:59:24
> ------------------------------ XFMail ------------------------------