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

[Bjarni Ingi Gislason <bjarniig@rhi.hi.is>]

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