• Antelope Release 5.10 Linux CentOS release 7.6.1810 (Core) 3.10.0 2020-05-12

 

NAME

antelope_man_page - Guidelines for constructing Antelope man pages

DESCRIPTION

Every program should have a man page which describes the program and its usage. The man page should probably have an example, and it should mention the author.

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):


% manpage -

Without the dash argument, there are a lot of explanatory comments which have to be deleted.

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.

Graphics

You may insert references to graphics into man pages, using the syntax:
  .IP "graphic:<reference-to-graphic>"
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.

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>"

EXAMPLE

See the existing man pages for examples.

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.


 .IP graphic:antelope.jpg

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.

Look at the dbe man page for an example of a document reference.

SEE ALSO

contrib(5)
dbe(1)

AUTHOR

Daniel Quinlan
Printer icon