doc: fix linter warnings and typos in manpage
Rendered preview of updated manpage
Checklist
-
documentation is changed or added -
commit message follows commit guidelines
Uncertain how to detail this, as it combines a menial self-explanatory fix (#1 below) and even more menial fixes which aren't self-explanatory (#2 below).
Changes
--preserve-symlinks-main
switch:
1. This PR fixes a typo introduced in #19911 with the new https://github.com/nodejs/node/blob/810af50ba2ab20e006a9e480b911c763f001ce8e/doc/node.1#L148
That F1
(U+0046 U+0031
) should really be Fl
(U+0046 U+006C
). The "Fl" is an abbreviation for "Flag"
In @dgoldstein0's defence, it was an easy mistake to make at a glance, because GitHub's code-font uses awkwardly-similar glyphs for 1
and l
. However, thanks to my killer work on Roff's syntax highlighting (used on GitHub), the discrepancy is easy to notice:
Anyway, the formatted output currently looks like this:
--preserve-symlinks
Instructs the module loader to …
F1 -preserve-symlinks-main
Instructs the module loader to …
--prof-process
Process V8 profiler output gene…
Now, that's actually legal markup, because the mdoc
formatter has no way of knowing you didn't mean to insert the text F1
. OTOH, .F1
would have been caught by the linter, since a line starting with a dot always introduces a command/macro, so it couldn't be misconstrued as being a plain-text line.
\-
, which I assume to be cargo-cult
2. I've removed the redundant use of Short explanation:
\-
is the same as writing -
.
Long explanation:
No, you don't want the long, painfully circuitous story behind -
VS \-
. Trust me, all you need to know now is that for terminal output, \-
is always the same as -
.
The only difference in manpage output is when using older versions of Groff with -Tutf8
set (Groff defaults to -Tascii
for terminal output, so even that's a non-issue. And even that difference is barely noticeable until you copy+paste it. Because in this lone scenario, -
(hyphen-minus U+002D
) gets replaced by -
(minus sign U+2212
).
\fB…\fR
) with mdoc .Sy
commands
3. I've replaced inline font sequences (Notice the spaces here?
.Sy ( - )
or underscores
.Sy ( _ ) .
That's much easier to follow than (\fB-\fR)
and (\fB_\fR)
, right? That's mdoc doing the hard work behind the scenes for you. When rendered, leading and trailing punctuation like this "closes in on" its contents, producing this:
(<b>-</b>) or underscores (<b>_</b>).
More about delimiter syntax here.