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
