kopia lustrzana https://github.com/Hamlib/Hamlib
rodzic
ce18ec7bf5
commit
516779cf03
|
@ -15,7 +15,8 @@ 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
|
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
|
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
|
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).
|
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 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
|
the future if the need arises. Conversely, the classic man macros are
|
||||||
|
@ -96,6 +97,8 @@ in the Hamlib man pages:
|
||||||
.nf Do not justify following text (encloses the .MT block)
|
.nf Do not justify following text (encloses the .MT block)
|
||||||
.fi Resume justification
|
.fi Resume justification
|
||||||
|
|
||||||
|
Note: ".br" and ".sp" should be used sparingly.
|
||||||
|
|
||||||
Structure
|
Structure
|
||||||
---------
|
---------
|
||||||
|
|
||||||
|
@ -109,7 +112,7 @@ Layout Tips
|
||||||
===========
|
===========
|
||||||
|
|
||||||
Keep in mind that roff documents are most often processed in a single pass,
|
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
|
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
|
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
|
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
|
lines. As a result, best practice is to not include blank lines in the
|
||||||
|
@ -122,16 +125,8 @@ 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
|
".PP", some tools may only recognize ".PP". One such tool is the older
|
||||||
'man2html' converter.
|
'man2html' converter.
|
||||||
|
|
||||||
Blank lines may be included as part of an example block placed between the
|
Headings
|
||||||
".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
|
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
|
between the previous text and the heading and also begins the next block of
|
||||||
|
@ -143,6 +138,70 @@ 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
|
from the left margin and the block of text that follows. Only one level of
|
||||||
sub-headings is provided.
|
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
|
Getting Help
|
||||||
============
|
============
|
||||||
|
|
Ładowanie…
Reference in New Issue