[net.text] man pages and formatting standards: request for comments

rdh@sun.uucp (Robert Hartman) (08/22/86)

As someone who regularly maintain man pages that originate
from Berkeley, AT&T, and other sources, I would welcome any
comments people have about the current format, font conventions, 
general style, cross-referencing conventions, and naming conventions, etc.

The emergence of PostScript means that the appearance and usability
UNIX reference manuals can be greatly improved.  The 4.3 version of the
man command allows man pages to be preprocessed with tbl, pic, and eqn,
and preformatted (with troff or a formatter of your choice) for laser
printers and bitmapped screens.  I would welcome any and all
suggestions about how to take advantage of these new features to
improve the man pages in a standardized way.

This might include new font conventions, standards for laying out
tables and diagrams, and easier methods for integrating (possibly
non-troff) sources into the online documentation set (for both
bitmapped and terminal displays), as well as filters to convert 
existing man pages to a newer fomat.

The reason I'm bringing this up is that I think that people
are going to want to make these kinds of improvements (myself, for
one), and I'd prefer to arrive at some standards before various people
take off willy-nilly in incompatible directions.  There has already 
been quite enough ad-hoc evolution of man pages so far.

This may also be a good time to take a look at how the man pages 
function in a reference manual vs. online, and how to get the most 
benefit from each type of use (has anyone ever actually paged through 
the entire csh man page online?).

Backward compatibility is important; one should always be able
to produce a man page on dumb-terminals and dot-matrix printers.
Still, there is no reason to continue to live within the limits
of these devices when better ones are available.

I will summarize any useful comments I receive and post them.  If
people are interested in discussing this further, I'll create a
mailing list.  At some point I'd like to propose a standard for
future UNIX reference pages and online documentation.  The more
comments I get, the better the proposal is likely to be.

-bob.