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

[J William Piggott <elseifthen@gmx.com>]

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
>