Skip to content

doc: fix linter warnings and typos in manpage

Rodrigo Muino Tomonari requested to merge github/fork/Cutlery-Drawer/typo-fix into master

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

1. This PR fixes a typo introduced in #19911 with the new --preserve-symlinks-main switch:

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:

Figure 1

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.

2. I've removed the redundant use of \-, which I assume to be cargo-cult

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).

3. I've replaced inline font sequences (\fB…\fR) with mdoc .Sy commands

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.

Merge request reports