groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Ralph Corderoy
Subject: Re: [Groff] Is there a good man page style guide somewhere?
Date: Sat, 13 Oct 2001 12:50:18 +0100

Hi Peter,

> I'm learning [gt]roff in order to write good man pages for some of my
> software

Yep, that was my first exposure through _The Unix Programming
Environment_.

    http://cm.bell-labs.com/cm/cs/upe/index.html

(Takes a while to load because of all the book cover art.)

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.

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

> and one problem I'm encountering is that I'm not exactly sure what a
> man page *should* look like.  I've been advised to look at existing
> man pages and copy what I see there, but there are subtle differences
> and I'm not sure which is better.

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

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

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.

> perlrun(1) is inconsistent with itself, putting no space in "[ -Idir
> ]" and "[ -Fpattern ]", but a space in "[ -e 'command' ]".

-I allows a space and -e works without out.

    % perl -I /tmp -le'print "@INC"'
    /tmp /usr/lib/perl5/i386-linux/5.00404 /usr/lib/perl5 /usr/lib/perl5
    /site_perl/i386-linux /usr/lib/perl5/site_perl .

I'd guess `-Idir' is used because C compiler's traditionally don't
allow a space for this option and that's where Perl borrowed it from.

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

> Is there a reference guide somewhere?  (And is there somewhere else I
> should be asking?)o

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

Cheers,


Ralph.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]