Hamlib/doc

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!