On Mon, 16 Dec 2019, Bjarni Ingi Gislason wrote:
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.
All inline escapes make the *source* difficult to read, maintain, are error
prone, and hostile for text-to-speech. That was a big problem in html source
decades ago and part of the reason that css was invented.
I wish you luck. I tried to convince this project that inline escapes should be
avoided, but everyone here seems to be in love with them. I had them all
stripped out of hwclock(8), but another contributor kept insisting on putting
them back. I finally gave up and started using them too.
###
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"]
That must be Debian hack, but Michael should adopt a no inline-escape policy
for the man page project, IMO. Although it shouldn't limited to italic.
###
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".
This is Michael's policy, and a good one I think. It would be a big task to do
this for the whole project.
Or
b) Adjust space between sentences (two spaces),
This is what the project currently does (is supposed to do).
c) or protect the indicator by adding "\&" after it.
The "indicator" is an "end-of-sentence character" (.!?).
This is called line termination, all three of which are not always;
hence the reason to make the distinction in roff.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
If you can convince Karl to adopt any of these rules then you should include
the chosen ones in the project documentation.
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
Remove the old, don't comment it.
Same for below.
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
