doc: howto-man-page.txt: Use font macros instead of font escapes
Subsystems (2)
PATCH 1/1 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.
--- Documentation/howto-man-page.txt | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-)
Documentation/howto-man-page.txt +18 -10
@@ -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
Signature · 1 line
2.24.0
Quoted 7 lines · Bjarni Ingi Gislason
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.
Quoted 9 lines
###
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.
Quoted 4 lines
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.
Quoted 9 lines
###
Change a HYPHEN-MINUS (code
0x55, 2D) to a minus (\-), if in front of a1) name for an option
2) negative number to be printed.
Quoted 7 lines
###
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.
Quoted 4 lines
Or
b) Adjust space between sentences (two spaces),
This is what the project currently does (is supposed to do).
Quoted 4 lines
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.
Quoted 3 lines
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.
Quoted 11 lines
Signed-off-by Bjarni Ingi Gislason <[email protected]>---
Documentation/howto-man-page.txt| 28 ++++++++++++++++++----------1 file changed, 18 insertions(+), 10 deletions(-)Documentation/howto-man-page.txt +0
-0@@ -30,10 +30,13 @@ Each manual page needs some sort of description of the command.
Quoted 6 lines
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.
Quoted 71 lines
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 wordDocumentation/howto-man-page.txt +0
-0@@ -59,18 +62,22 @@ to be the same, but in fact the former is two separate options while thelater 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 orDocumentation/howto-man-page.txt +0
-0@@ -105,7 +112,8 @@ one..\"
.PP
When in the source a new sentence begins somewhere midline, it should use aDocumentation/howto-man-page.txt +2
-1-double space before its initial letter. This is done because \fBgroff\fR +double space before its initial letter. This is done because +.B groffuses 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
Documentation/howto-man-page.txt +0
-0@@ -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,Documentation/howto-man-page.txt +0
-0@@ -171,7 +179,7 @@ etc.RE
.SH AUTHORS
.MT rjh@\:example.orgDocumentation/howto-man-page.txt +1
-1-Random J. Hacker +Random J.\& Hacker.ME
.br
.MT fred@\:example.com
--
2.24.0
Quoted 6 lines · J William Piggott
Quoted 2 lines · Bjarni Ingi Gislason
Use font macros instead of font escapes (\f[BIPR]).
[...]
Quoted 5 lines
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.
No reason to give up.
Comment the font-escape line and
add the font-macro line after it.
People need to see the difference easily.
Quoted 9 lines
Quoted 9 lines
###
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.
Quoted 8 lines
Quoted 4 lines
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.
My pointing to reference [1] is wrong,
as there is no instruction about using a macro
instead of a font escape request.
Quoted 1 line
Quoted 1 line
[...]
Quoted 9 lines
Quoted 5 lines
.SH OPTIONS
.TP
-\fB\-n\fR, \fB\-\-no\-argument\fR +.BR \-n ,\ \-\-no\-argument
+.\" \fB\-n\fR, \fB\-\-no\-argument\fRRemove the old, don't comment it.
Same for below.
Showing the commented out font-escape line is better,
so that the reader sees the difference and
how the transformation is made.
The commented old line should come first
to prepare the user for the changed (maybe strange) line.
I find now the use of escaped space (,\ ) worse
than using a quotation (", ").
[...]
Signature · 1 line
Bjarni I. Gislason
Quoted 7 lines · Bjarni Ingi Gislason
Quoted 6 lines · J William Piggott
Quoted 2 lines · Bjarni Ingi Gislason
Use font macros instead of font escapes (\f[BIPR]).
Quoted 8 lines
[...]
Quoted 5 lines
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.
No reason to give up.
Well, yes there was, but there's no point in going into it.
Quoted 2 lines
Comment the font-escape line and
add the font-macro line after it.
If I had submitted a patch like that it would have been rejected (although I would not do that to a production man page anyway).
Quoted 1 line
People need to see the difference easily.
Many people believe inline escapes are okay, or even better.
Quoted 15 lines
Quoted 15 lines
Quoted 14 lines
###
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"]
Quoted 7 lines
Quoted 3 lines
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.
My pointing to reference [1] is wrong,
as there is no instruction about using a macro instead of a font escape request.
Well, I still agree with you on not using them. Maybe you can convince Michael to add it to man-pages(7)?
Quoted 13 lines
Quoted 2 lines
Quoted 2 lines
[...]
Quoted 9 lines
Quoted 5 lines
.SH OPTIONS
.TP
-\fB\-n\fR, \fB\-\-no\-argument\fR +.BR \-n ,\ \-\-no\-argument
+.\" \fB\-n\fR, \fB\-\-no\-argument\fRRemove the old, don't comment it.
Same for below.
Quoted 5 lines
Showing the commented out font-escape line is better,
so that the reader sees the difference and
how the transformation is made.
The commented old line should come first
to prepare the user for the changed (maybe strange) line.
I can understand one example of 'what not to do' (that should be visible when viewing the page with man(1)). But, IMO, filling the page with unwanted comments just adds clutter.
Quoted 3 lines
I find now the use of escaped space (,\ ) worse
than using a quotation (", ").
I haven't formed a strong opinion on this. I use both depending on which appears the most readable to me (in the source code) and whether having a line break in the formatted output is unwanted.
Quoted 6 lines
[...]
--
Bjarni I. Gislason
Karel Zak
maintainerQuoted 6 lines · J William Piggott
Quoted 2 lines · Bjarni Ingi Gislason
Comment the font-escape line and
add the font-macro line after it.If I had submitted a patch like that it would have been rejected (although I would not do that to a production man page anyway).
Well, frankly... I don't like man-page (re)formatting patches :-)
It's maintainer's nightmare -- always is there someone who hates the change, it's difficult review all the details and keep all consistent if you have large collection of man pages from different sources/authors, etc.
For me the best would be to maintain *content* in some formatting independent data format like AsciiDoc or DocBook, and before release or during package build process generate wanted output according a user-specified template; it's only a way how to support user or distro specific point of view.
For example asciidoctor (AsciiDoc backend) is actively maintained and used by projects like github. Not sure about readability of the final man pages, but it seems that AsciiDoc -> DocBook -> man page is possible way.
And for example systemd guys maintain man pages directly in XML DocBook.
IMHO it's way to go rather than for ever play "color of bike shed" game with our man pages.
“Content is King” :-) Volunteers?
Karel
Signature · 2 lines
Karel Zak <[email protected]> http://karelzak.blogspot.com