doc: howto-man-page.txt: Use font macros instead of font escapes
Use font macros instead of font escapes (\f[BIPR]). The escape '\c' ("connect to next input text") is used to join the output of two macros without a space character. This is similar to the '\' escape at the end of a line. Font escapes make the text more difficult to read. ### Changes based on: Use a macro to change to the italic font, instead of \fI [1], if possible. The macros have the italic corrections, but "\c" removes the "\/" part. Or add the italic corrections. [1] man-pages(7) [Debian package "manpages"] ### Change a HYPHEN-MINUS (code 0x55, 2D) to a minus (\-), if in front of a 1) name for an option 2) negative number to be printed. ### Wrong distance between sentences or protect the indicator. a) Separate the sentences and subordinate clauses; each begins on a new line. See man-pages(7) [package "manpages"] and "info groff". Or b) Adjust space between sentences (two spaces), c) or protect the indicator by adding "\&" after it. The "indicator" is an "end-of-sentence character" (.!?). The amount of space between sentences in the output can then be controlled with the ".ss" request. Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
This commit is contained in:
parent
1c4c602427
commit
37f26093c9
|
@ -30,10 +30,13 @@ Each manual page needs some sort of description of the command.
|
||||||
Write such here.
|
Write such here.
|
||||||
.SH OPTIONS
|
.SH OPTIONS
|
||||||
.TP
|
.TP
|
||||||
\fB\-n\fR, \fB\-\-no\-argument\fR
|
.BR \-n ,\ \-\-no\-argument
|
||||||
|
.\" \fB\-n\fR, \fB\-\-no\-argument\fR
|
||||||
This option does not use an argument.
|
This option does not use an argument.
|
||||||
.TP
|
.TP
|
||||||
\fB\-\-optional\fR[\fI=argument\fR]
|
.BR \-\-optional [ =\c
|
||||||
|
.IR argument ]
|
||||||
|
.\" \fB\-\-optional\fR[\fI=argument\fR]
|
||||||
Tell in this description that the
|
Tell in this description that the
|
||||||
.I argument
|
.I argument
|
||||||
is optional, and what happens when it is or is not given. Notice that the word
|
is optional, and what happens when it is or is not given. Notice that the word
|
||||||
|
@ -59,18 +62,22 @@ to be the same, but in fact the former is two separate options while the
|
||||||
later will use
|
later will use
|
||||||
.B n
|
.B n
|
||||||
as option argument of
|
as option argument of
|
||||||
.BR -o .
|
.BR \-o .
|
||||||
So it is best to avoid short forms of optional options altogether.
|
So it is best to avoid short forms of optional options altogether.
|
||||||
.TP
|
.TP
|
||||||
\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
|
.BR \-r ,\ \-\-required\ \c
|
||||||
|
.I argument
|
||||||
|
.\"\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
|
||||||
Tell in this description that the
|
Tell in this description that the
|
||||||
.I argument
|
.I argument
|
||||||
is required.
|
is required.
|
||||||
.TP
|
.TP
|
||||||
\fB\-V\fR, \fB\-\-version\fR
|
.BR \-V ", " \-\-version
|
||||||
|
.\"\fB\-V\fR, \fB\-\-version\fR
|
||||||
Display version information and exit.
|
Display version information and exit.
|
||||||
.TP
|
.TP
|
||||||
\fB\-h\fR, \fB\-\-help\fR
|
.BR \-h ,\ \-\-help
|
||||||
|
.\"\fB\-h\fR, \fB\-\-help\fR
|
||||||
Display help text and exit.
|
Display help text and exit.
|
||||||
.SH NOTES
|
.SH NOTES
|
||||||
Tell details that users might need to know. For example, kernel feature or
|
Tell details that users might need to know. For example, kernel feature or
|
||||||
|
@ -105,7 +112,8 @@ one.
|
||||||
.\"
|
.\"
|
||||||
.PP
|
.PP
|
||||||
When in the source a new sentence begins somewhere midline, it should use a
|
When in the source a new sentence begins somewhere midline, it should use a
|
||||||
double space before its initial letter. This is done because \fBgroff\fR
|
double space before its initial letter. This is done because
|
||||||
|
.B groff
|
||||||
uses a double space after a sentence when this sentence ends at the end of
|
uses a double space after a sentence when this sentence ends at the end of
|
||||||
an input line and the next sentence begins on the next line.
|
an input line and the next sentence begins on the next line.
|
||||||
Unless a double space is used before other sentence starts as well, the
|
Unless a double space is used before other sentence starts as well, the
|
||||||
|
@ -139,10 +147,10 @@ Another file.
|
||||||
Write typical and/or clever use examples here. The below examples are stupid,
|
Write typical and/or clever use examples here. The below examples are stupid,
|
||||||
and you should never write them in a real man page.
|
and you should never write them in a real man page.
|
||||||
.TP
|
.TP
|
||||||
.B example -h
|
.B example \-h
|
||||||
Output help screen.
|
Output help screen.
|
||||||
.TP
|
.TP
|
||||||
.B example -V
|
.B example \-V
|
||||||
Output version information.
|
Output version information.
|
||||||
.SH "EXIT STATUS"
|
.SH "EXIT STATUS"
|
||||||
This section can be left out if the command has only two return values,
|
This section can be left out if the command has only two return values,
|
||||||
|
@ -171,7 +179,7 @@ etc
|
||||||
.RE
|
.RE
|
||||||
.SH AUTHORS
|
.SH AUTHORS
|
||||||
.MT rjh@\:example.org
|
.MT rjh@\:example.org
|
||||||
Random J. Hacker
|
Random J.\& Hacker
|
||||||
.ME
|
.ME
|
||||||
.br
|
.br
|
||||||
.MT fred@\:example.com
|
.MT fred@\:example.com
|
||||||
|
|
Loading…
Reference in New Issue