* Re: Replace \f where appropriate
2023-07-16 2:22 Replace \f where appropriate Alejandro Colomar
@ 2023-07-16 2:58 ` G. Branden Robinson
0 siblings, 0 replies; 2+ messages in thread
From: G. Branden Robinson @ 2023-07-16 2:58 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man
[-- 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 --]
^ permalink raw reply [flat|nested] 2+ messages in thread