From 37f26093c985a95d5bda9842b1a4fb2f415bb1c3 Mon Sep 17 00:00:00 2001 From: Bjarni Ingi Gislason Date: Mon, 16 Dec 2019 22:20:32 +0000 Subject: [PATCH] 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 --- 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