kopia lustrzana https://github.com/Hamlib/Hamlib
156 wiersze
6.6 KiB
Plaintext
156 wiersze
6.6 KiB
Plaintext
|
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:
|
||
|
|
||
|
hamlib-developer@lists.sourceforge.net
|
||
|
|
||
|
73!
|