Skip to contentSkip to conversation

doc: howto-man-page.txt: Use font macros instead of font escapes

PATCH In review Bjarni Ingi Gislason 3 participants 5 messages Dec 16, 2019 – Jan 3, 2020

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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
index 55734af91..f2b352dac 100644
@@ -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
#1 lore raw
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 a

1) 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

---
Documentation/howto-man-page.txt | 28 ++++++++++++++++++----------

1 file changed, 18 insertions(+), 10 deletions(-)
Documentation/howto-man-page.txt +0 -0
index 55734af91..f2b352dac 100644
@@ -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 word

Documentation/howto-man-page.txt +0 -0
@@ -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

Documentation/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 a

Documentation/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 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

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.org

Documentation/howto-man-page.txt +1 -1
-Random J. Hacker
+Random J.\& Hacker

.ME
.br
.MT fred@\:example.com
--
2.24.0

#2 lore raw
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\fR

Remove 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
#3 lore raw
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\fR

Remove 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

maintainer
#4 lore raw
Quoted 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