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 display of "problematic" ASCII characters #44373

Merged
merged 1 commit into from Oct 21, 2022
Merged

doc: fix display of "problematic" ASCII characters #44373

merged 1 commit into from Oct 21, 2022

Conversation

Alhadis
Copy link
Contributor

@Alhadis Alhadis commented Aug 24, 2022

When preparing output for a terminal that supports Unicode, Groff remaps the following characters to typographically "fancier" versions:

^ (U+005E)  ->  ˆ (U+02C6)
~ (U+007E)  ->  ˜ (U+02DC)
- (U+002D)  ->  ‐ (U+2010)
` (U+0060)  ->  ‘ (U+2018)
' (U+0027)  ->  ’ (U+2019)

This transformation is normally desirable in high-quality typeset output (i.e., PDF and PostScript), but frequently problematic in terminal display. As described in groff_char(7), the following escape sequences are needed to display the aforementioned characters as they appear in source code:

^   ->   \(ha   (Mnemonic: "hat")
~   ->   \(ti   (Mnemonic: "tilde")
-   ->   \-
`   ->   \(ga   (Mnemonic: "grave accent")
'   ->   \(aq   (Mnemonic: "apostrophe quote")

These constructs are cumbersome to write, obstruct readability of source code, and are completely opaque to the majority of man page authors (who only care about terminal display). A simpler solution is to use Roff's .tr to translate these characters automatically.

When preparing output for a terminal that supports Unicode, Groff remaps
the following characters to typographically "fancier" versions:

    ^ (U+005E)  ->  ˆ (U+02C6)
    ~ (U+007E)  ->  ˜ (U+02DC)
    - (U+002D)  ->  ‐ (U+2010)
    ` (U+0060)  ->  ‘ (U+2018)
    ' (U+0027)  ->  ’ (U+2019)

This transformation is normally desirable in high-quality typeset output
(PDF and PostScript), but frequently problematic in terminal display. As
described in groff_char(7), the following escape sequences are needed to
display the aforementioned characters as they appear in source code:

    ^   ->   \(ha   (Mnemonic: "hat")
    ~   ->   \(ti   (Mnemonic: "tilde")
    -   ->   \-
    `   ->   \(ga   (Mnemonic: "grave accent")
    '   ->   \(aq   (Mnemonic: "apostrophe quote")

These constructs are cumbersome to write, obstruct readability of source
code, and are completely opaque to the majority of man page authors (who
only care about terminal display). A simpler solution is to use `.tr` to
translate these characters automatically.
@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Aug 24, 2022
@Alhadis
Copy link
Contributor Author

Alhadis commented Oct 21, 2022

@jasnell Is this blocked on anything?

@jasnell jasnell added the commit-queue Add this label to land a pull request using GitHub Actions. label Oct 21, 2022
@nodejs-github-bot nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Oct 21, 2022
@nodejs-github-bot nodejs-github-bot merged commit 9dddc6a into nodejs:main Oct 21, 2022
@nodejs-github-bot
Copy link
Collaborator

Landed in 9dddc6a

@Alhadis Alhadis deleted the man-punct branch October 21, 2022 15:12
@jasnell
Copy link
Member

jasnell commented Oct 21, 2022

Looks like it just fell through the cracks. Landed now!

@Alhadis
Copy link
Contributor Author

Alhadis commented Oct 21, 2022

Awesome, thank you! 🎉

RafaelGSS pushed a commit that referenced this pull request Nov 1, 2022
When preparing output for a terminal that supports Unicode, Groff remaps
the following characters to typographically "fancier" versions:

    ^ (U+005E)  ->  ˆ (U+02C6)
    ~ (U+007E)  ->  ˜ (U+02DC)
    - (U+002D)  ->  ‐ (U+2010)
    ` (U+0060)  ->  ‘ (U+2018)
    ' (U+0027)  ->  ’ (U+2019)

This transformation is normally desirable in high-quality typeset output
(PDF and PostScript), but frequently problematic in terminal display. As
described in groff_char(7), the following escape sequences are needed to
display the aforementioned characters as they appear in source code:

    ^   ->   \(ha   (Mnemonic: "hat")
    ~   ->   \(ti   (Mnemonic: "tilde")
    -   ->   \-
    `   ->   \(ga   (Mnemonic: "grave accent")
    '   ->   \(aq   (Mnemonic: "apostrophe quote")

These constructs are cumbersome to write, obstruct readability of source
code, and are completely opaque to the majority of man page authors (who
only care about terminal display). A simpler solution is to use `.tr` to
translate these characters automatically.

PR-URL: #44373
Reviewed-By: James M Snell <jasnell@gmail.com>
@RafaelGSS RafaelGSS mentioned this pull request Nov 1, 2022
RafaelGSS pushed a commit that referenced this pull request Nov 10, 2022
When preparing output for a terminal that supports Unicode, Groff remaps
the following characters to typographically "fancier" versions:

    ^ (U+005E)  ->  ˆ (U+02C6)
    ~ (U+007E)  ->  ˜ (U+02DC)
    - (U+002D)  ->  ‐ (U+2010)
    ` (U+0060)  ->  ‘ (U+2018)
    ' (U+0027)  ->  ’ (U+2019)

This transformation is normally desirable in high-quality typeset output
(PDF and PostScript), but frequently problematic in terminal display. As
described in groff_char(7), the following escape sequences are needed to
display the aforementioned characters as they appear in source code:

    ^   ->   \(ha   (Mnemonic: "hat")
    ~   ->   \(ti   (Mnemonic: "tilde")
    -   ->   \-
    `   ->   \(ga   (Mnemonic: "grave accent")
    '   ->   \(aq   (Mnemonic: "apostrophe quote")

These constructs are cumbersome to write, obstruct readability of source
code, and are completely opaque to the majority of man page authors (who
only care about terminal display). A simpler solution is to use `.tr` to
translate these characters automatically.

PR-URL: #44373
Reviewed-By: James M Snell <jasnell@gmail.com>
danielleadams pushed a commit that referenced this pull request Dec 30, 2022
When preparing output for a terminal that supports Unicode, Groff remaps
the following characters to typographically "fancier" versions:

    ^ (U+005E)  ->  ˆ (U+02C6)
    ~ (U+007E)  ->  ˜ (U+02DC)
    - (U+002D)  ->  ‐ (U+2010)
    ` (U+0060)  ->  ‘ (U+2018)
    ' (U+0027)  ->  ’ (U+2019)

This transformation is normally desirable in high-quality typeset output
(PDF and PostScript), but frequently problematic in terminal display. As
described in groff_char(7), the following escape sequences are needed to
display the aforementioned characters as they appear in source code:

    ^   ->   \(ha   (Mnemonic: "hat")
    ~   ->   \(ti   (Mnemonic: "tilde")
    -   ->   \-
    `   ->   \(ga   (Mnemonic: "grave accent")
    '   ->   \(aq   (Mnemonic: "apostrophe quote")

These constructs are cumbersome to write, obstruct readability of source
code, and are completely opaque to the majority of man page authors (who
only care about terminal display). A simpler solution is to use `.tr` to
translate these characters automatically.

PR-URL: #44373
Reviewed-By: James M Snell <jasnell@gmail.com>
danielleadams pushed a commit that referenced this pull request Dec 30, 2022
When preparing output for a terminal that supports Unicode, Groff remaps
the following characters to typographically "fancier" versions:

    ^ (U+005E)  ->  ˆ (U+02C6)
    ~ (U+007E)  ->  ˜ (U+02DC)
    - (U+002D)  ->  ‐ (U+2010)
    ` (U+0060)  ->  ‘ (U+2018)
    ' (U+0027)  ->  ’ (U+2019)

This transformation is normally desirable in high-quality typeset output
(PDF and PostScript), but frequently problematic in terminal display. As
described in groff_char(7), the following escape sequences are needed to
display the aforementioned characters as they appear in source code:

    ^   ->   \(ha   (Mnemonic: "hat")
    ~   ->   \(ti   (Mnemonic: "tilde")
    -   ->   \-
    `   ->   \(ga   (Mnemonic: "grave accent")
    '   ->   \(aq   (Mnemonic: "apostrophe quote")

These constructs are cumbersome to write, obstruct readability of source
code, and are completely opaque to the majority of man page authors (who
only care about terminal display). A simpler solution is to use `.tr` to
translate these characters automatically.

PR-URL: #44373
Reviewed-By: James M Snell <jasnell@gmail.com>
danielleadams pushed a commit that referenced this pull request Jan 3, 2023
When preparing output for a terminal that supports Unicode, Groff remaps
the following characters to typographically "fancier" versions:

    ^ (U+005E)  ->  ˆ (U+02C6)
    ~ (U+007E)  ->  ˜ (U+02DC)
    - (U+002D)  ->  ‐ (U+2010)
    ` (U+0060)  ->  ‘ (U+2018)
    ' (U+0027)  ->  ’ (U+2019)

This transformation is normally desirable in high-quality typeset output
(PDF and PostScript), but frequently problematic in terminal display. As
described in groff_char(7), the following escape sequences are needed to
display the aforementioned characters as they appear in source code:

    ^   ->   \(ha   (Mnemonic: "hat")
    ~   ->   \(ti   (Mnemonic: "tilde")
    -   ->   \-
    `   ->   \(ga   (Mnemonic: "grave accent")
    '   ->   \(aq   (Mnemonic: "apostrophe quote")

These constructs are cumbersome to write, obstruct readability of source
code, and are completely opaque to the majority of man page authors (who
only care about terminal display). A simpler solution is to use `.tr` to
translate these characters automatically.

PR-URL: #44373
Reviewed-By: James M Snell <jasnell@gmail.com>
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.

None yet

3 participants