There is a standard template for man pages, which gets them off on the right foot. You can look at this template with the command manpage(1):
Without the dash argument, there are a lot of explanatory comments which have to be deleted.% manpage -
All man pages are converted from troff to html with a program, troff2html. It has a variety of limitations, so it's best to stick to these few simple constructions inside the man page:
.IP | indented paragraph |
.LP | left justified paragraph |
.SH | major section |
.SS | sub section |
.TS | start table |
.TE | stop table |
.TH | header line |
.br | break |
.nf | no fill |
.fi | fill |
.ft | new font B, R, CW |
.in | indent |
.ne | keep lines on same page |
.sp | space |
\fI | italic |
\fB | bold |
\fP | return to previous font |
Always switch from the default font R to B or I or CW and then switch back
using "\fP" or ".ft P".
The translation to html and/or wiki format does not support eqn, and has only
limited support for tbl. In particular, only the default tab character <tab>
is recognized in tables.
Run your man page through fixman -nd your-manpage.x for some additional
feedback.
When translated to the html or the wiki version, this will be replaced by the actual graphic. The actual graphic must also be installed, using the antelopemake macro GRAPHIC, similar to BIN, MAN1, PF, etcetera. Images are installed into $ANTELOPE/html/graphic. For consistency and reasonable displays, graphic images should probably be no more than 850 pixels wide. Jpeg appears to give the smallest file sizes, which is a benefit on the wiki at least..IP "graphic:<reference-to-graphic>"
Similarly, you may insert references to pdf documents into man pages, and they will be replaced with references to the installed location. Again, the pdf document has to be installed, this time using the antelopemake macro DOC -- documents are installed into $ANTELOPE/doc.
.IP "doc:<reference-to-pdf>"
Here's are some example of graphic references. This is how a local reference would appear in the man page text; the actual graphic file should have been installed into $ANTELOPE/man/graphic, using the builtin rule for the GRAPHIC macro and targets.
This is how that reference is rendered. Try man antelope_man_page to see the regular man page; go to http:$ANTELOPE/man/html/antelope_man_page.1.html to see how it appears in html..IP graphic:antelope.jpg
Look at the dbe man page for an example of a document reference.
contrib(5) dbe(1)