Man page notes

For the assignment two man-page-writing requirement, you probably want to skim that document, or maybe mostly just read some of the beginning and then use it for reference.

But there are some important central points which you don't want to miss. Here is a summary of some of them.

• The man page style is terse. Don't digress. Don't talk about other man pages or commands hardly at all (just cite them) (but do cite them where useful).

• Never include any sections just because they're there. A section whose contents is "None" or "Nothing to discuss" is a negative thing -- your reader wastes time, however tiny, just skipping the blather. One offender in this regard which I would like to single out is the COPYRIGHT and REPORTING BUGS sections in GNU man pages. These really shouldn't be there. While copyright might be important, it does not need to be asserted in this particular place, and it just results in padding. To some extent this is a repetition of the previous point: The man page style is terse.

• There is an exception to the previous point, though, which is that the NAME section is used for automatic index building, so should always be present. As well, the DESCRIPTION section is just about always going to be relevant. And for volume 1 (commands), SYNOPSIS is always relevant, even if all it says is the command name (thus indicating that there should be no command-line arguments).

• Use standard formats. Man pages are processed by standard tools. Man pages are also processed by standard unix-programming humans. Both of these agents expect the man pages to be in a certain format and work best with that format. Use standard section headings. See TEMPLATE for a template (but remember to delete sections which are empty or trivial!).

• There are specific semantics of the components in the SYNOPSIS section for volume 1 (commands). Square brackets, brace brackets, and even the use of fonts (bold/italic) is standardized. Please see "Unix Programmer's Manual Conventions" in manpage.pdf, especially near the bottom of page 4 through the examples on page 5.
• Don't follow the GNU man page style of saying "command [options] files". This has no semantic content. List the options in the standard syntax as in the above-cited examples on page 5 of manpage.pdf.

• Man pages describe the command (or library function or file format or whatever) from the outside; do not discuss its internals, don't say whether it's a C program or a shell script, etc. The internals should be documented in files accompanying the source code (e.g. in comments in the source code, or supplementary text files where useful).

• Your man pages are part of the "Unix Programmer's Manual". Do not use the .MA macro.