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

[peter]

Thank you all for the responses!

Ralph Corderoy wrote:
> In its chapter on hoc it covers writing a man page and the `source for
> the hoc calculator' is available from the above page, including the
> hoc.1 man page.

Thank you; that's a small but useful example.

> There's also source of the entire Unix 7th Edition available online
> which lets you see how man pages were written by the originators of
> tmac.an before outside influences crept in much.

>     http://plan9.bell-labs.com/7thEdMan/index.html

Most useful!  sort.1 is an example of a complex command line.
But even here, there's confusion.  sort.1 puts a space in
"-o name" and "-T directory", while tc.1 and plot.1 omit
the spaces.  Of course, perhaps they were required to be absent;
V7 could be a bit inconsistent on that subject.

> Obviously, people's opinions differ.  Here's mine :-)

> Does the program accept one of `-z9' or `-z 9', or both?  If it only
> accepts one style then the man page must match.  If either then the
> spaced version is preferable.

In my case,it follwos the getopt convnetion of accepting both.
And I agree that I prefer to document it with the space.

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

> IMO, no.  We don't use spaces in written English and the man page reads
> more easily if [ and ] aren't words on their own.

I didn't either; I found that those spaces made it hard to see what the
brackets were bracketing.  Of course, it made for some tricky coding:

.\" Some font-changing stuff that's cluttered to do directly.
.\" I'd use \*[, but that's a groff extension.  Remember to include the
.\" italic corrections \/ and \,.  Oops, those are groff extensions,
too,
.\" so define wrappers \*, and \*/...
.ie '\,',' .ds , \&
.el .ds , \,
.ie '\/'/' .ds / \^
.el .ds / \/
.\" Now define always-roman brackets that can be placed next to bold
options
.\" and italic arguments.
.ds < \fR[\fP
.ds > \*/\fR]\fP
.\" And one for roman ellipses, sensibly spaced.
.ds . \fR\|.\|.\|.\fP

which leads to an option definition like:

.BI \*<\-r\  hostname \*/\*<: port\*>\fR]\fP\*.

(Note the lack of extra space between the two ]]; in gorff it would be
safe to put \/ there anyway, but the troff kludge just puts \^ always.)

Then there's the question of do you want more or less verbose:
.B \*<\-qq
|
.B \-vvv\*>

Here, I think the space around the or-bar is useful.

> I know of no reference guide.  Try google.  Personally, I've copied
> Bell Labs and kept both the nroff and troff output in mind.

Yes, I think I'll take that as Canon.  Much obliged!



Bernd Warken wrtye:

> If the program used POSIX getopt() or getopt_long(), see getopt(3), or 
> getopt(1) on the command line the space is optional, while 
> getopt_long_only() makes the space a must.  For readability reasons,
> it is better to add a space between the command and its argument 
> whenever possible because POSIX allows strange option clusters of single
> character options behind a single '-'.

Yes, my personal opinion on what looks good agrees with you there.

> man(7) should define the standard. But it seems to be out-of-date and
> badly supported. Moreover, there were incompatibilities with groff.

That would be a good place, but even here, we can't agree on what it
should be.

> So, ye oulde man fellows, get together and remount the horse!

I realize I'm not an oulde man fellowe, but I'm not entirely sure what
"remounting the horse" means here.  It's a common metaphor for
continuing after a setback, but...?



Speaking of not agreeing on The Right Thing,
Clarke Echols wrote:

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

I'm sorry I wasn't clear that I was assuming the getopt convention 
where the space is optional and made everyone worry about the case
where it might not be.

But I notice that you disagree about the preferred form if it's
optional.  Interesting!  It does tend to cause more italic collisions.

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

H'm... the use of Courier rather than bold is certainly a departure.
It certainly is commonly used for "literal" text, so it's hardly
a bad thing, but I think it would be a bit discordant in if I were
to use it in just one place.

>> 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 agree.  But groff(1) takes the opposite view.  It's confusing to the
poor newbie.

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

>From my brief survey, this seems quite necessary!
I don't think I can get away with the same sort of overhaul, but thank
you for sharing the story.


Sometimes it just takes the right experience to understand why one way
of doing things is better than another.  To pick an example from a field
I'm more familiar with, I have abandoned
        const char *p;
in favor of
        char const *p;

After someone explained how putting the const *after* the type provides
consistent behaviour in presence of typedefs.

Think for a while about which of the following are equivalent:

        typedef char *pointer;
1)      const pointer p;
2)      pointer const p;
3)      const char *p;
4)      char const *p;
5)      char * const p;

1) and 2) are equivalent to 5) and no others.  If you're in the habit
of writing 4), it's much more obvious that you can't sneak the const
"between" the parts of the typedef.  The non-equivalence of 1) and 3)
is a little more confusing.