My problem is, after a project nearing completion, it's time to focus on things like documentation, one of which is the man page.
Now, people may or may not dislike man pages, but it's pretty much standard to be shipped with a tool for Linux.
My problem is, however, finding information about how exactly to structure and write one.
I know there are some rough guidelines, which sections should always be included, etc. but I rely mostly on already written man pages for things like
base64 to get an idea how to (correctly) write one.
The problem is, they differ immensely in their style.
The man page of
base64 uses the regular commands like
.TP, but doesn't use the
.OP command usually used for option tables. however it uses the troff-like escape sequences:
.TP \fB\-d\fR, \fB\-\-decode\fR decode data
It is quite simplistic, so to say.
The man page of
groff is a whole different story. It uses things like
.SY and the
.OP command for switches in the synopsis:
.SH SYNOPSIS .\" -------------------------------------------------------------------- . .SY groff .OP \-abcegijklpstzCEGNRSUVXZ .OP \-d cs .OP \-D arg .OP \-f fam ...
It uses prety much no escape sequences at all, instead the text is structures like this:
.TP .B \-j Preprocess with .BR chem . . Implies .BR \-p .
i.e. using troff commands instead of escape sequences.
There are other examples similar to these, anyone who wrote a man page, is aware of the diverse styles, etc.
At this point, I'm quite confused as to which style I should follow. At least some reference guide would be nice, and basically possibly a primer or something as to how this should be approached. (for instance, I haven't figured out what the
.SY command does, etc.)
These pages were a helpful start, but I quickly exhausted their usefulness:
EDIT: Some more information in man pages
Thanks, Stephen Harris.