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\fRdecode dataIt 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 \-jPreprocess 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:http://www.linuxhowtos.org/System/creatingman.htmhttps://www.linux.com/news/what-you-need-know-write-man-pageshttp://liw.fi/manpages/EDIT: Some more information in man pageshttp://man7.org/linux/man-pages/man7/groff_man.7.htmlhttp://man7.org/linux/man-pages/man7/mdoc.samples.7.htmlhttp://man7.org/linux/man-pages/man7/mdoc.7.htmlThanks, Stephen Harris.
How and what style should I use when writing man pages?
man;documentation
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 withman 7 manman 7 mdocSo things like .Op are only valid using mdocEither version should be fine on modern systems; I'd probably consider mdoc format.