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

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

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

###
  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>
---
 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
-- 
2.24.0

Re: [PATCH] doc: howto-man-page.txt: Use font macros instead of font escapes

[J William Piggott]

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@rhi.hi.is>
> ---
> 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
>

Re: [PATCH] doc: howto-man-page.txt: Use font macros instead of font escapes

[Bjarni Ingi Gislason]

On Tue, Dec 17, 2019 at 03:43:15PM -0500, J William Piggott wrote:
> 
> 
> On Mon, 16 Dec 2019, Bjarni Ingi Gislason wrote:
> 
> > Use font macros instead of font escapes (\f[BIPR]).
> >
[...]
> 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.

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

  My pointing to reference [1] is wrong,
as there is no instruction about using a macro
instead of a font escape request.

> >
[...]
> >.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 (", ").

[...]

-- 
Bjarni I. Gislason

Re: [PATCH] doc: howto-man-page.txt: Use font macros instead of font escapes

[J William Piggott]

On Thu, 2 Jan 2020, Bjarni Ingi Gislason wrote:

> On Tue, Dec 17, 2019 at 03:43:15PM -0500, J William Piggott wrote:
>>
>>
>> On Mon, 16 Dec 2019, Bjarni Ingi Gislason wrote:
>>
>>> Use font macros instead of font escapes (\f[BIPR]).
>>>
> [...]
>> 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.

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

> People need to see the difference easily.

  Many people believe inline escapes are okay, or even better.

>
>>>
>>> ###
>>> 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.
>>
>
>  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)?

>
>>>
> [...]
>>> .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 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.

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

>
> [...]
>
> --
> Bjarni I. Gislason
>

Re: [PATCH] doc: howto-man-page.txt: Use font macros instead of font escapes

[Karel Zak]

On Thu, Jan 02, 2020 at 11:52:06AM -0500, J William Piggott wrote:
> On Thu, 2 Jan 2020, Bjarni Ingi Gislason wrote:
> > 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


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com