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>

diff --git a/Documentation/howto-man-page.txt b/Documentation/howto-man-page.txt
index 55734af9157c028804c2f78b46a44afa279a0bda..f2b352dac7173dbb3201171d28d96480213468df 100644 (file)
--- 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