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

docs: normalize plaintext code blocks #33028

Closed
wants to merge 16 commits into from

Conversation

zeke
Copy link
Contributor

@zeke zeke commented Apr 23, 2020

The PR normalizes txt, fundamental, and raw fenced code blocks in markdown files to use text as the info string (i.e. language).

Resolves #32938

Checklist

cc @nodejs/documentation

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Apr 23, 2020
doc/api/report.md Outdated Show resolved Hide resolved
doc/api/http2.md Outdated Show resolved Hide resolved
doc/api/http2.md Outdated Show resolved Hide resolved
@DerekNonGeneric
Copy link
Contributor

DerekNonGeneric commented Apr 24, 2020

@zeke, I have a couple of concerns w/ your PR. The primary one being that we aren't nipping this in the bud. Ideally, we would be banning the txt info string while providing a suggestion for text. This would happen in remark-preset-lint-node. I fear you may have jumped the gun on this one and would have to defer further work on this PR until @Trott has made some comments in #32938.

@zeke
Copy link
Contributor Author

zeke commented Apr 24, 2020

Okay. Happy to help with an update to https://github.com/nodejs/remark-preset-lint-node if that seems like the right course of action.

defer further work on this PR until @Trott has made some comments in #32938.

Looks like @Trott has already weighed in there. Were you expecting further comment?

@DerekNonGeneric
Copy link
Contributor

DerekNonGeneric commented Apr 24, 2020

Were you expecting further comment?

Absolutely. If not in that particular issue, in this PR (or elsewhere). I would give it some time.

Copy link
Contributor

@DerekNonGeneric DerekNonGeneric left a comment

Choose a reason for hiding this comment

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

I've put a bit more thought into exactly what info strings are available and what they all mean. I will followup this review comment w/ a PR augmenting the documentation guide clarifying my suggestions. Hopefully, it will be persuasive enough to take these suggestions. :)

doc/api/tracing.md Outdated Show resolved Hide resolved
doc/guides/building-node-with-ninja.md Outdated Show resolved Hide resolved
doc/api/util.md Outdated Show resolved Hide resolved
doc/api/util.md Outdated Show resolved Hide resolved
doc/api/tracing.md Outdated Show resolved Hide resolved
doc/api/tracing.md Outdated Show resolved Hide resolved
doc/api/modules.md Outdated Show resolved Hide resolved
doc/api/errors.md Outdated Show resolved Hide resolved
doc/api/http.md Outdated Show resolved Hide resolved
doc/api/http2.md Outdated Show resolved Hide resolved
zeke and others added 10 commits May 26, 2020 16:23
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>
@BridgeAR BridgeAR added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label May 27, 2020
BridgeAR pushed a commit to BridgeAR/node that referenced this pull request May 30, 2020
These are changed to either ```text or ```console.

PR-URL: nodejs#33028
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
@BridgeAR
Copy link
Member

Landed in f08174c

@BridgeAR BridgeAR closed this May 30, 2020
@DerekNonGeneric
Copy link
Contributor

/re #33028 (comment) and #33028 (comment)

After updating the bundle to include the HTTP grammar, I noticed that although this is an HTTP request [almost] following HTTP semantics, it also includes linebreak escape characters.

This results in the sub-par highlighting as seen below. :(

image

I wonder if this is a deficiency in the highlighter's regex or this should have actually been text.

image

  • Should I forgo my intention of highlighting http info strings?
  • Will the new QUIC implementation include http info strings in its docs?

/cc @jasnell

@Trott
Copy link
Member

Trott commented Jun 7, 2020

  • Should I forgo my intention of highlighting http info strings?

In the particular case from your screenshot, I think removing \r\n is appropriate. (As a general rule, I would think you can either show \n explicitly and not render the line break, or else there is no need to show \n. Since there are rendered line breaks here, the \r\n is not necessary to show.)

codebytere pushed a commit that referenced this pull request Jun 18, 2020
These are changed to either ```text or ```console.

PR-URL: #33028
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Trott pushed a commit that referenced this pull request Jun 25, 2020
This commit adds the list of agreed-upon info strings to the
documentation style guide to aid with future development and
maintenance.

Refs: #33510
Refs: #33507
Refs: #33483
Refs: #33531
Refs: #33542
Refs: #33028
Refs: #33548
Refs: #33486

PR-URL: #34024
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
codebytere pushed a commit that referenced this pull request Jun 27, 2020
This commit adds the list of agreed-upon info strings to the
documentation style guide to aid with future development and
maintenance.

Refs: #33510
Refs: #33507
Refs: #33483
Refs: #33531
Refs: #33542
Refs: #33028
Refs: #33548
Refs: #33486

PR-URL: #34024
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
@codebytere codebytere mentioned this pull request Jun 28, 2020
codebytere pushed a commit that referenced this pull request Jun 30, 2020
These are changed to either ```text or ```console.

PR-URL: #33028
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
codebytere pushed a commit that referenced this pull request Jun 30, 2020
This commit adds the list of agreed-upon info strings to the
documentation style guide to aid with future development and
maintenance.

Refs: #33510
Refs: #33507
Refs: #33483
Refs: #33531
Refs: #33542
Refs: #33028
Refs: #33548
Refs: #33486

PR-URL: #34024
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
codebytere pushed a commit that referenced this pull request Jul 8, 2020
These are changed to either ```text or ```console.

PR-URL: #33028
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
codebytere pushed a commit that referenced this pull request Jul 10, 2020
This commit adds the list of agreed-upon info strings to the
documentation style guide to aid with future development and
maintenance.

Refs: #33510
Refs: #33507
Refs: #33483
Refs: #33531
Refs: #33542
Refs: #33028
Refs: #33548
Refs: #33486

PR-URL: #34024
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
codebytere pushed a commit that referenced this pull request Jul 12, 2020
This commit adds the list of agreed-upon info strings to the
documentation style guide to aid with future development and
maintenance.

Refs: #33510
Refs: #33507
Refs: #33483
Refs: #33531
Refs: #33542
Refs: #33028
Refs: #33548
Refs: #33486

PR-URL: #34024
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
@codebytere codebytere mentioned this pull request Jul 13, 2020
codebytere pushed a commit that referenced this pull request Jul 14, 2020
This commit adds the list of agreed-upon info strings to the
documentation style guide to aid with future development and
maintenance.

Refs: #33510
Refs: #33507
Refs: #33483
Refs: #33531
Refs: #33542
Refs: #33028
Refs: #33548
Refs: #33486

PR-URL: #34024
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
author ready PRs that have at least one approval, no pending requests for changes, and a CI started. doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Inconsistent use of plaintext code fencing in docs
6 participants