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.