man pages: Keyboard shortcuts/keys and other style questions

Marco Steinbach coco at
Tue Sep 7 17:00:43 UTC 2010


I'm currently preparing a man page for a yet to be submited new port,
and altough I was able to get answers for some of my questions from the
mdoc(7) man page and other sources, there are still some areas where I
am not sure about how to properly format and label things.

If this list is not the right place to post such questions, I'd
appreciate any pointers (e.g. -ports ?).

The current source of the man page is available at

The port has an optional ncurses-based interface, which, if used, allows 
the behaviour of the utility to be changed by pressing certain keys.

- Is "INTERACTIVE MODE" the appropiate term to be used as heading for 
the section dealing with the specifics of a ncurses-based user interface ?

- What labels are to be used for keys which usually do not produce a 
printable character ? E.g. is the <return>-key to be represented as 
"return", "<return>" or "RETURN" (or is it to be named "enter", anyway ?)

- What about the cursor movement and other directional keys like 
<cursor-left/right/up/down>, <pageup/down>, <home/end> ?

- Are there any preferences for the macros to use for keys to be 
pressed, e.g. is the following acceptable:
.Bl -tag -width Fl
.It Ic C
Do the C thing.
.It Ic A
Do the A thing.

Any hints and suggestions (wording, macro usage, etc) to make the man 
page a better fit to the style of the FreeBSD project are greatly 

MfG CoCo

More information about the freebsd-doc mailing list