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

[Ted Harding]

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 ------------------------------