man page style questions

[Chip Camden]

Quoth Marco Steinbach on Saturday, 11 September 2010:
> I'm reposting this to -ports, as I got no replies on -doc within several 
> days.
> 
> 
> 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.
> 
> The current source of the man page is available at
> http://www.moehre.org/files/sqtop/sqtop.1
> 
> 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.
> .El
> 
> 
> 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
> appreciated.
> 
> MfG CoCo
> 
> _______________________________________________
> freebsd-ports at freebsd.org mailing list
> http://lists.freebsd.org/mailman/listinfo/freebsd-ports
> To unsubscribe, send any mail to "freebsd-ports-unsubscribe at freebsd.org"

I'm glad you asked this question.  I don't have any answers, but I am
eagerly awaiting some authoritative replies.  AFAIK, we're lacking in
guidelines here.

-- 
Sterling (Chip) Camden    | sterling at camdensoftware.com | 2048D/3A978E4F
http://camdensoftware.com | http://chipstips.com        | http://chipsquips.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 488 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/freebsd-ports/attachments/20100911/f134173d/attachment.pgp