Main / Man Pages

Half a century after its creation, the Unix manual page format remains a good template for technical documentation and more.

Database sections

Only needed for actual man pages meant to be installed on a Unix system. (But worth keeping in mind anyway.) The section number is used as file extension in that case.

Sections 5, 6 and 7 are of general interest, as they go beyond the technicalities of an operating system.

1. User commands

Of interest to anyone with an account on the system.

2. System calls

For low-level kernel stuff(?)

3. Library calls

Mostly for C, Perl and Tcl.

4. Special files (devices)

Advanced OS usage.

5. File formats and configuration files

Apparently intended for reference documentation. Overviews and such should probably go in (7) below.

6. Games

Doesn't have to be computer games. For example Risus, "the anything RPG", can be easily made into a manual page.

7. Overviews, conventions and miscellaneous

On Linux, manual page guidelines are documented in man-pages(7); on NetBSD, they're in mdoc(7) instead.

8. System commands

For administrators.

Section headers

This document only includes section headers used in most manual pages, not only for commands and/or functions. The list can be added to or trimmed, but standard sections used at all should appear in order and with these names.

Subsections are allowed, but the number of levels should be kept minimal.

NAME (mandatory)

Subject - one-line description after a dash

SYNOPSIS (mandatory)

Can list multiple commands or whatever as one logical group.

DESCRIPTION (mandatory)

Doesn't have to be long or detailed.

OPTIONS

Best interpreted loosely. For example, in a tabletop RPG optional rules can go here.

FILES

For software, this means files used by the program during normal operation, such as config and so on. Other kinds of projects will require creativity.

NOTES

Exactly that.

BUGS

Arguably makes sense only for software. Or does it?

EXAMPLES

Just enough to get people started with common use cases.

AUTHORS

Linux documentation guidelines say not to use this. Obviously that doesn't apply to other projects. Contact information goes here.

COPYRIGHT

For licensing and ownership information(?)

SEE ALSO (mandatory)

Lists other manual pages normally, but might need to be interpreted flexibly in some cases.

How to make Unix manual pages

• Write as Perl POD, convert with pod2man and pod2html. The latter in particular emits very clean markup.
• Write as AsciiDoc, convert with the eponymous tool or else AsciiDoctor.
• For Python modules, the pydoc / pydoc3 tool generates documentation in a very similar format.

Notes

• Many if not most Linux manual pages follow guidelines poorly if at all.

Attach:man-pages.md