Add some tips on Hamlib man pages formatting

doc/Makefile.am

@@ -8,7 +8,7 @@ htmldir = $(docdir)/html
 dist_html_DATA = Hamlib_design.png hamlib.html
 
 SRCDOCLST = ../src/rig.c ../src/rotator.c ../src/tones.c ../src/locator.c \
-		../src/event.c ../src/conf.c ../src/mem.c ../src/settings.c
+	../src/event.c ../src/conf.c ../src/mem.c ../src/settings.c
 
 info_TEXINFOS = hamlib.texi
 hamlib_TEXINFOS = nutshell.texi getting_started.texi utility_programs.texi \

doc/README.man-pages

@@ -0,0 +1,155 @@
+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 pacakges 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).
+
+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
+
+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.
+
+Blank lines may 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
+from the shell, programs, or blocks of source code.
+
+Examples should be indented from the blocks of text.  The ".RS 0.5i" macro is
+used for indentation of normal text blocks while ".RS 1.0i" is used for
+indented text blocks, such as a block indented using the ".TP" macro.  For
+each case the indented block must be followed by the ".RE" macro to return the
+next block of text to the normal indentation level.
+
+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.
+
+
+Getting Help
+============
+
+If something is unclear on how to format a new or updated man page, simply
+post your question to the mailing list:
+
+        [email protected]
+
+73!