Guidelines for updating and authoring new man pages. Overview ======== The man pages are written in the roff formatting language. See roff(7) ("man roff") for an overview. roff is implemented on modern Unix like systems by groff (GNU roff) which is a suite of programs and macro definition files that make up the roff system. Documentation written in roff can be transformed into a number of formats for final publication. For the Hamlib project, the output formats are the classic man(1) format to a terminal screen, HTML, and PDF. While groff includes a number of macro packages suitable for a variety of document styles, Hamlib source files are written using the man(7) macro package. The layout of Hamlib man pages generally follow the format specified in man-pages(7). The macros used in the man pages format is specified in groff_man(7). Additional style cues can be found in groff_man_style(7). The use of mdoc from the BSD projects has been considered and may be used in the future if the need arises. Conversely, the classic man macros are reasonably well understood, fairly simple, easy to use, can be processed by a wide range of tools, and fits the Hamlib philosophy of being as approachable as possible. To be fair, mdoc is very comprehensive and would allow many more formatting choices to be available for the various output formats. At some point mdoc may well be the better choice. The latest versions of the manual pages referenced above may be found at: http://man7.org/linux/man-pages/dir_section_7.html For information on mdoc, see: http://mandoc.bsd.lv/ Recommended Practices ===================== Sections -------- The man pages are sorted into various sections depending on the part of the system they document. For Hamlib, the man pages fall into one of three categories. The placement is as follows: Section Hamlib subject domain 1 Executables, rigctl, rotctl, etc. 3 Hamlib library constants and functions. 7 General Hamlib information. Macros and escapes ------------------ The use of man macros to mark up the roff source files is strongly encouraged. In some cases, the use of lower level troff font escapes, such as "\fBxxx\fP", is required, but should be used sparingly. Such escapes are hard to read and not all editors can highlight the escape correctly. The default font for HTML and PDF is Roman (often Times Roman on the local system) and rarely needs to be specified directly with the ".R" macro. Text may be bolded using the ".B" macro or italicized using the ".I" macro. A set of combination macros exist that combine alternating sequences of styled text such as ".BR" for alternating Bold and Roman text. In the OPTIONS and COMMANDS sections of the utility pages there are complex constructs of the form of: .BR M ", " set_mode " \(aq" \fIMode\fP "\(aq \(aq" \fIPassband\fP \(aq The result is that the command strings will be in Bold, the punctuation will be in Roman, and the names of the variables will be in Italics using the low level troff font escapes. Quoted strings are required to ensure spacing between items as the ".BR" macro uses (and other combination macros) spaces to separate its arguments. As you can see, the font escapes are hard to read as they must be run up tight against the text. Special symbols such as copyright or trademark glyphs and styled quotation marks do require roff escapes inlined with the text. Several such escapes can be found in the Hamlib roff source files: Escape Description \(aq ASCII single quote \(oq Styled opening single quote \(cq Styled closing single quote \(lq Styled opening double quote \(rq Styled closing double quote \(co Copyright symbol Besides the macros documented in man(7), the following troff macros are used in the Hamlib man pages: Macro Description .br Line break (analogous to '\n' in C) .sp Line break plus an additional blank line .nf Do not justify following text (encloses the .MT block) .fi Resume justification Note: ".br" and ".sp" should be used sparingly. Structure --------- In addition to the standard man page sections of NAME, SYNPOPSIS, etc., the Hamlib utility (section 1) man pages add the sections COMMANDS, READLINE, PROTOCOL, DIAGNOSTICS, COPYRIGHT, and COLOPHON depending on the individual utility. Layout Tips =========== Keep in mind that roff documents are most often processed in a single pass, i.e., the document processor reads the file from top to bottom and formats the text per the macros and escapes found along the way. Anything that is not a macro or an escape gets rendered into the output file and that includes blank lines. As a result, best practice is to not include blank lines in the running text. Instead use the ".PP" or ".IP" macros to indicate a paragraph or an indented paragraph break. To provide vertical spac between elements of the source document, a single '.' on a line will be discarded by the document processor. This provides a way to visually separate paragraphs and headings. Note: While the man macro package recognizes ".LP" and ".P" as synonyms for ".PP", some tools may only recognize ".PP". One such tool is the older 'man2html' converter. Headings -------- Normal section headings use the ".SH" macro which provides for vertical space between the previous text and the heading and also begins the next block of running text. All text blocks must follow a heading. Headings are normally composed of one word in all capital letters. Sub-headings use the ".SS" macro which provides vertical space above the previous block of text and indents the sub-heading to about half the distance from the left margin and the block of text that follows. Only one level of sub-headings is provided. Examples -------- Examples should be indented from the blocks of text. The ".in +4n" macro is used for indentation of four characters regardless of text indentation level. Precede each such macro with either the ".PP" or the ".IP" macro, the latter being used with a block indented using the ".TP" macro. The indented block must be ended using the ".in" macro to return the next block of text to the normal indentation level. In the Hamlib man pages this indentation is combined with the ".EX" and ".EE" macro pair. See the man1/rigctl.1 file for examples. Blank lines should be included as part of an example block placed between the ".EX" and ".EE" macros. Lines between these macros are rendered in HTML and PDF as blocks of constant width text and should be verbatim input or output in the shell, programs, or blocks of source code. Text intended to be typed at a shell or program prompt should be in bold and program orshell output in normal weight. In some cases it will be necessary to use the "\fB...\fP" font formatting calls especially where backslash escapes ("\\") are required. Notes ----- Notes are those asides that bring attention to an important bit of information. Indent the note with the ".IP" macro in all levels of text. Bold the word "Note" and set the colon in Roman, e.g., ".BR Note :". Testing ======= While writing a manual page it is very useful to check the output. Terminal output --------------- At the shell prompt this may be done with: man ./manual_page.1 This will direct the man program to format the file in question rather than searching through its database. PDF and HTML output ------------------- It is very useful to generate PDF and HTML files while writing a manual page to assure the font effects and indentation are as you intend. Use these commands to generate these files: groff -mandoc -Tpdf >manual_page.1.pdf manual_page.1 groff -mandoc -Thtml >manual_page.1.html manual_page.1 Use your favorite PDF viewer and browser to view them. Getting Help ============ If something is unclear on how to format a new or updated man page, simply post your question to the mailing list: hamlib-developer@lists.sourceforge.net 73!