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@xxxxxxxxx>
---
Documentation/howto-man-page.txt | 28 ++++++++++++++++++----------
1 file changed, 18 insertions(+), 10 deletions(-)
diff --git a/Documentation/howto-man-page.txt b/Documentation/howto-man-page.txt
index 55734af91..f2b352dac 100644
--- a/Documentation/howto-man-page.txt
+++ b/Documentation/howto-man-page.txt
@@ -30,10 +30,13 @@ Each manual page needs some sort of description of the command.
Write such here.
.SH OPTIONS
.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.
.TP
-\fB\-\-optional\fR[\fI=argument\fR]
+.BR \-\-optional [ =\c
+.IR argument ]
+.\" \fB\-\-optional\fR[\fI=argument\fR]
Tell in this description that the
.I argument
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
.B n
as option argument of
-.BR -o .
+.BR \-o .
So it is best to avoid short forms of optional options altogether.
.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
.I argument
is required.
.TP
-\fB\-V\fR, \fB\-\-version\fR
+.BR \-V ", " \-\-version
+.\"\fB\-V\fR, \fB\-\-version\fR
Display version information and exit.
.TP
-\fB\-h\fR, \fB\-\-help\fR
+.BR \-h ,\ \-\-help
+.\"\fB\-h\fR, \fB\-\-help\fR
Display help text and exit.
.SH NOTES
Tell details that users might need to know. For example, kernel feature or
@@ -105,7 +112,8 @@ one.
.\"
.PP
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
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
@@ -139,10 +147,10 @@ Another file.
Write typical and/or clever use examples here. The below examples are stupid,
and you should never write them in a real man page.
.TP
-.B example -h
+.B example \-h
Output help screen.
.TP
-.B example -V
+.B example \-V
Output version information.
.SH "EXIT STATUS"
This section can be left out if the command has only two return values,
@@ -171,7 +179,7 @@ etc
.RE
.SH AUTHORS
.MT rjh@\:example.org
-Random J. Hacker
+Random J.\& Hacker
.ME
.br
.MT fred@\:example.com
--
2.24.0
