docs: normalize plaintext code blocks by zeke · Pull Request #33028 · nodejs/node

zeke · 2020-04-23T18:09:45Z

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

documentation is changed or added
commit message follows commit guidelines

cc @nodejs/documentation

doc/api/report.md

doc/api/http2.md

DerekNonGeneric · 2020-04-24T16:04:31Z

@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 · 2020-04-24T16:10:40Z

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 · 2020-04-24T16:19:17Z

Were you expecting further comment?

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

DerekNonGeneric

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

doc/guides/building-node-with-ninja.md

doc/api/util.md

doc/api/tracing.md

doc/api/modules.md

doc/api/errors.md

doc/api/http.md

doc/api/http2.md

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

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 · 2020-05-30T01:44:08Z

Landed in f08174c

DerekNonGeneric · 2020-06-07T11:43:12Z

/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. :(

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

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 · 2020-06-07T13:08:45Z

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

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>

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>

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>

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>

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>

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>

zeke added 3 commits April 23, 2020 11:01

docs: change txt code blocks to text

79d30b5

docs: change fundamental code block to text

439d081

docs: change raw code block to text

403494b

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Apr 23, 2020

DerekNonGeneric reviewed Apr 23, 2020

View reviewed changes

doc/api/report.md Outdated Show resolved Hide resolved

docs: update text (formerly raw) code block to ```console

2fdcd07

zeke mentioned this pull request Apr 23, 2020

Inconsistent use of plaintext code fencing in docs #32938

Closed

5 tasks

DerekNonGeneric reviewed Apr 24, 2020

View reviewed changes

doc/api/http2.md Outdated Show resolved Hide resolved

zeke commented Apr 24, 2020

View reviewed changes

doc/api/http2.md Outdated Show resolved Hide resolved

Update doc/api/http2.md

d2bb8c8

DerekNonGeneric approved these changes May 25, 2020

View reviewed changes

DerekNonGeneric reviewed May 25, 2020

View reviewed changes

zeke and others added 10 commits May 26, 2020 16:23

Update doc/guides/building-node-with-ninja.md

300c21c

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

Update doc/api/util.md

4077339

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

Update doc/api/errors.md

c7c91ad

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

Update doc/api/http2.md

568bbf9

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

Update doc/api/http.md

995e428

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

Update doc/api/modules.md

2ace334

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

Update doc/api/util.md

ed4162c

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

Update doc/api/tracing.md

27c59e9

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

Update doc/api/tracing.md

292c841

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

Update doc/api/tracing.md

9e2c40c

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

jasnell approved these changes May 27, 2020

View reviewed changes

Update doc/api/tracing.md

317cf70

Co-authored-by: Derek Lewis <DerekNonGeneric@inf.is>

BridgeAR approved these changes May 27, 2020

View reviewed changes

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 closed this May 30, 2020

codebytere mentioned this pull request Jun 28, 2020

v14.5.0 proposal #34093

Merged

codebytere mentioned this pull request Jul 13, 2020

v12.18.3 proposal #34343

Merged

Uh oh!

Conversation

zeke commented Apr 23, 2020

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DerekNonGeneric commented Apr 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zeke commented Apr 24, 2020

Uh oh!

DerekNonGeneric commented Apr 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DerekNonGeneric left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BridgeAR commented May 30, 2020

Uh oh!

DerekNonGeneric commented Jun 7, 2020

Uh oh!

Trott commented Jun 7, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

DerekNonGeneric commented Apr 24, 2020 •

edited

Loading

DerekNonGeneric commented Apr 24, 2020 •

edited

Loading