Re: [Groff] Is there a good man page style guide somewhere?

[Clarke Echols]

I was responsible for the HP-UX man pages from 1985 through 1992 (HP-UX 5.0
through 9.0), though I had full editorial control only beginning in 1989.
There are no standards per se, but I can comment based on what I did for
HP's man pages.

> There are a whole bunch of little details that seem worth getting right.
> When typesetting the option "[-z level]", should there be a space between
> "-z" and "level"?  I have seen it both ways.  The groff(1) man page omits
> the space, but my Debian man(1) man page inclides them.

If the parser requires a space, then use a space.  If it does not, do not
include a space.  In the man macros, I defined a .C, .CI, .CR, and .CB
macro, although the .CB was never used.  These were equivalent to the
.BR, .BI, etc. macros, with C being defined on font position 4, using
Courier font.  I then used .CI and .IC to intermingle literals and symbolics,
using \c as a continuation at the end of a line if I did not want any
whitespace between the last character on that line and the first character
of the next line in the source file.
> 
> perlrun(1) is inconsistent with itself, putting no space in
> "[ -Idir ]" and "[ -Fpattern ]", but a space in "[ -e 'command' ]".

I would have coded these as:

.RC [ I\c
.IR dir ]

or as:

[\|\c
.CI -I dir\|\c
] [\|\c
.CI -X option\|\c
]

etc.

The last one I would have coded as
[\|\c
.CI -e' command '\|\c
]

I used \| to provide a little "air" between the square brackets and the
actual option or argument.  It made a nicer looking typography.

> 
> Should there be a space (\ , or something different?) between the option
> brackets and the option inside?  Again, groff(1) includes these spaces,
> but man(1) and man(7) omit them.

\(space) is too wide.  That's why I used \| instead.

> 
> (I happen to like the latter better visually, but the former seems more
> prevalent in "classic" Unix man pages.  But interestingly, SunOS 4.1.4
> troff(1) and man(1) are styled just like their Linux counterparts...)
> 
> To say nothing of the issues that show up in parts other than SYNOPSIS.
> 
> Is there a reference guide somewhere?
> (And is there somewhere else I should be asking?)o

I wrote a man page on how to write man pages, but it was not made
available outside of HP, and I don't have a copy since I retired.

When I took control in 1989, there was no "standard" way of doing things.
I wrote a sed script to do a lot of conversion into my preferred standard,
then imposed it on all manpages for Starbase graphics, networking, and
the usual HP Unix stuff (that previously was kept lock-step with the text
in AT&T manpages so they could diff changes easily).  With the advent of
POSIX, that need for control went away, and I wrested editorial and
formatting control from the previous powers that be, and did a complete
overhaul of the entire format, layout, and typography.

In 1993, the project was moved to California from Colorado, and later the
source files were moved to SGML with a translation to troff, and I do not
know the details of how things were done from that point on.