From a3a788cbf7856bafa3b7caebbc2889aaf11b99d0 Mon Sep 17 00:00:00 2001 From: Nate Bargmann Date: Thu, 3 May 2018 07:31:12 -0500 Subject: [PATCH] Add some tips on Hamlib man pages formatting --- doc/Makefile.am | 2 +- doc/README.man-pages | 155 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 doc/README.man-pages diff --git a/doc/Makefile.am b/doc/Makefile.am index a06d195af..835b117b7 100644 --- a/doc/Makefile.am +++ b/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 \ diff --git a/doc/README.man-pages b/doc/README.man-pages new file mode 100644 index 000000000..88434b3d2 --- /dev/null +++ b/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: + + hamlib-developer@lists.sourceforge.net + +73!