Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: fix linter warnings and typos in manpage #20741

Closed
wants to merge 1 commit into from
Closed

doc: fix linter warnings and typos in manpage #20741

wants to merge 1 commit into from

Conversation

Alhadis
Copy link
Contributor

@Alhadis Alhadis commented May 15, 2018

Rendered preview of updated manpage

Checklist
Changes

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

node/doc/node.1

Line 148 in 810af50

.It F1 -preserve-symlinks-main

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.

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label May 15, 2018
@Alhadis
Copy link
Contributor Author

Alhadis commented May 15, 2018

/cc @silverwind

Also, I propose we eradicate the lowercase form of L from the Latin alphabet, because even with bilateral serifs, it's still confusable with another character. With no serifs, it's indistinguishable from a capital I, so what the hell is this damn thing doing in our alphabet? 😀

Copy link
Member

@BridgeAR BridgeAR left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RSLGTM

@dgoldstein0
Copy link
Contributor

sorry for the typo... I totally was just cargo-culting and didn't know that it was Fl and not F1. Thanks for fixing.

@Alhadis
Copy link
Contributor Author

Alhadis commented May 15, 2018

No need to apologise, mate. 😉I'm glad I could help. I might be the only Roff-fluent JavaScript programmer on Earth.

.if \\n(NX<=1 .if \\n(AJ=0 .if \\n(FT=0 .ll \\n(LLu
.if !\\n(IF \{\
.	ps \\n(PS
.	ie \\n(VS>=41 .vs \\n(VSu
.	el .vs \\n(VSp\}
.ie \\n(IP \{
. \"  ACCENTS  say \*'e or \*`e to get e acute or e grave both were 4/10
.ds ' \h'\w'e'u*1/10'\z\(aa\h'-\w'e'u*1/10'
.ds ` \h'\w'e'u*2/10'\z\(ga\h'-\w'e'u*2/10'
. \"  UMLAUT  \*:u, etc.
.if t .ds : \\v'-0.6m'\\h'(1u-(\\\\n(.fu%2u))*0.13m+0.00m'\\z.\\h'0.2m'\\z.\\h'-((1u-(\\\\n(.fu%2u))*0.13m+0.20m)'\\v'0.6m'
.if n .ds : \z"
. \" TILDE and CIRCUMFLEX
.ds ^ \\\\k:\\h'-\\\\n(.fu+1u/2u*2u+\\\\n(.fu-1u*0.13m+0.06m'\\z^\\h'|\\\\n:u'
.ds ~ \\\\k:\\h'-\\\\n(.fu+1u/2u*2u+\\\\n(.fu-1u*0.13m+0.06m'\\z~\\h'|\\\\n:u'

I just everybody could read what I'm reading and know how much they could do with it. 😢

Copy link
Member

@Trott Trott left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for fixing things up!

@Trott
Copy link
Member

Trott commented May 16, 2018

@Trott
Copy link
Member

Trott commented May 17, 2018

Landed in c8e7f8f

@Trott Trott closed this May 17, 2018
Trott pushed a commit to Trott/io.js that referenced this pull request May 17, 2018
Refs: nodejs#19911

PR-URL: nodejs#20741
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: James M Snell <[email protected]>
@Alhadis Alhadis deleted the typo-fix branch May 17, 2018 20:49
MylesBorins pushed a commit that referenced this pull request May 22, 2018
Refs: #19911

PR-URL: #20741
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: James M Snell <[email protected]>
@addaleax addaleax mentioned this pull request May 22, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants