Re: Replace \f where appropriate

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2340 bytes --]

Hi Alex,

At 2023-07-16T04:22:18+0200, Alejandro Colomar wrote:
> As you may have noticed, we're now using the recent SPDX tags, which
> were added in a recent SPDX release.  Next plan I have for the project
> is to stop using \f escapes where unnecessary.  I'll start tomorrow,

Hooray!  Let me reiterate, for those who are not man(7) experts, why
font style macros should be preferred, where possible, to \f escape
sequences.

* The macros integrate more easily with spell checking systems.
  Contrast
    .I length
  with
    \fIlenth\fP
  for example.

  Here, a text editor like vim(1) will mark the latter as misspelled
  because of the leading "fI", and you may not notice the actual
  spelling error within.  The many false positives frustrate page
  maintenance and lower page quality by increasing tolerance for
  spelling errors.

  groff's \f[] syntax for font changes is helpful here, but some
  projects want page sources that are portable to AT&T troff, which yet
  lives on Solaris 10 and possibly other places.  Such projects may also
  complain that the brackets require "more typing".

  Font style macros are less typing than both forms of escape sequence.

* In groff man(7), font style macros take care of italic corrections for
  you.  If you only ever read man pages at a terminal you won't care
  about this.  But if you want your man pages to look good in print,
  sooner or later you will start caring.

> Branden, since this may affect your work in scripting the change to
> start using the MR macro, I'll keep you updated about it.

I appreciate it.  I don't expect much frustration because my procedure
is as follows.

1.  Start from a clean checkout.
2.  Dump all the non-.so man pages as plain text[2] to a file.
3.  Execute a sed script.
4.  Dump all the non-.so man pages as plain text to another file.
5.  Diff the two text files.
6.  Revise the sed script.
7.  "git co man*"
8.  Go to step 3.

Eventually, I will be able to break the loop after step 5.

Regards,
Branden

[1] If a man page is updated more frequently than it is read, even by
    its sole author, I think it is likely to be of poor quality.
    Nevertheless, the world is not short of people who claim to produce
    perfect work on the first attempt, and groff attempts to serve them
    as well.

[2] groff -t -mandoc -T ascii -P -cbou

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]