4

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 groff, ssh, and 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 .SH and .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.

closed as primarily opinion-based by Thomas Dickey, Anthon, Stephen Harris, sam, MelBurslan Aug 12 '16 at 15:29

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • Consider using ronn (github.com/rtomayko/ronn) instead of writing raw groff. – PSkocik Aug 12 '16 at 4:45
  • 1
    I'd like to address whether this is opinion based or not: How else should I ask why there is a difference and which one to use? – polemon Aug 12 '16 at 22:33
3

The difference between the two versions are due to different macro sets; the original man set and the newer mdoc set. You can see what commands each one has with

man 7 man
man 7 mdoc

So things like .Op are only valid using mdoc

Either version should be fine on modern systems; I'd probably consider mdoc format.

  • Oh ok, seems like it's going into the right direction. I'm reading mdoc.samples right now, see if it's what I'm looking for. – polemon Aug 12 '16 at 3:51
  • It seems one other good source is groff_man(7) – polemon Aug 12 '16 at 4:26

Not the answer you're looking for? Browse other questions tagged or ask your own question.