doc: use consistent markdown in README by Trott · Pull Request #7971 · nodejs/node · GitHub

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

Changes include:

consistent header indications
wrap bare URLs in < and >
consistent emphasis indications
specifying a language in fenced code
wrapping at 80 characters

Linting tool possibly on the way.

I disagree, but I'm open to be persuaded. Bike shed time, I guess but here are the reasons:

This is a shell command. It may be bash. Or it maybe csh or zsh or tcsh or even Windows PowerShell. There is nothing bash-specific about curl.
If shell is not more appropriate than bash here, then when would it ever be more appropriate?
This is more of an argument that it doesn't matter than that one or the other is right, but bash is an alias for shell in the syntax highlighting tool used by GitHub Flavored Markdown so there is no difference in the rendered output of one versus the other.

¯_(ツ)_/¯

This should be either «```console» or commands should not start with «$».

Done.

Improve markdown practices in README: * consistent header indicators * consistent emphasis indicators * wrap bare URLs in `<` and `>` * wrap at 80 chars * specifying language in fenced code

ditto

This either shouldn't be «```console» or the lines should start with a prompt like «$ » or «> ».
Or this is going to be formatted like text output.

I would just use sh or shell here (in this specific block), perhaps.

One issue with a code block language specification (console → shell), everything else LGTM.

@ChALkeR Switched that one instance to shell. Thanks.

@Trott Ah, noticed one more thing.

$ gpg --keyserver pool.sks-keyservers.net \
  --recv-keys DD8F2338BAE7501E3DD5AC78C273792F7D83545D

is inaccurate and gets wrong highlight.

It should be either shell without the $ to allow copy-pasting the whole thing:

gpg --keyserver pool.sks-keyservers.net \
  --recv-keys DD8F2338BAE7501E3DD5AC78C273792F7D83545D

or console with a > on the second line to depicture the actual console behaviour and serve as an example:

$ gpg --keyserver pool.sks-keyservers.net \
>  --recv-keys DD8F2338BAE7501E3DD5AC78C273792F7D83545D

@ChALkeR I suppose another option is just to get rid of the line break and have it be a single line by itself. Does that work for you?

@Trott Yes, it does, it doesn't break the maximum-line-length rule.

It does break a guideline rule regarding the sources code style, but there is no other way to achieve a similar display and this looks like a valid reason for an exception. We already have those in other places (long links, for example).

LGTM.

LGTM

Continuing what a58b48b did for the doc/ dir, this fixes some formatting issues in the *.md files that are placed directly in the top-level directory. README.md changes are excluded as they are covered by #7971 Refs: #7637

LGTM!

Continuing what a58b48b did for the doc/ dir, this fixes some formatting issues in the *.md files that are placed directly in the top-level directory. README.md changes are excluded as they are covered by nodejs#7971 Refs: nodejs#7637 PR-URL: nodejs#7727 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Michaël Zasso <mic.besace@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Improve markdown practices in README: * consistent header indicators * consistent emphasis indicators * wrap bare URLs in `<` and `>` * wrap at 80 chars * specifying language in fenced code PR-URL: #7971 Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <mic.besace@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Landed in cc3a9e7!

Continuing what a58b48b did for the doc/ dir, this fixes some formatting issues in the *.md files that are placed directly in the top-level directory. README.md changes are excluded as they are covered by #7971 Refs: #7637 PR-URL: #7727 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Michaël Zasso <mic.besace@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Improve markdown practices in README: * consistent header indicators * consistent emphasis indicators * wrap bare URLs in `<` and `>` * wrap at 80 chars * specifying language in fenced code PR-URL: #7971 Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <mic.besace@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Trott added the doc Issues and PRs related to the documentations. label Aug 3, 2016

Fishrock123 reviewed Aug 3, 2016
View reviewed changes

doc: use consistent markdown in README

33fb018

Improve markdown practices in README: * consistent header indicators * consistent emphasis indicators * wrap bare URLs in `<` and `>` * wrap at 80 chars * specifying language in fenced code

Trott force-pushed the remark branch from bb8280c to 33fb018 Compare August 4, 2016 02:27

ChALkeR reviewed Aug 4, 2016
View reviewed changes

ChALkeR mentioned this pull request Aug 4, 2016

doc: more formatting fixes #7727

Merged

2 tasks

squash: shell -> console

8644a27

ChALkeR reviewed Aug 4, 2016
View reviewed changes

squash: console -> shell

7582f08

squash: single line command

3605f4b

ChALkeR mentioned this pull request Aug 4, 2016

tools: add remark-lint configuration in .remarkrc #7729

Merged

1 task

ChALkeR mentioned this pull request Aug 5, 2016

doc: use git-secure-tag for release tags #7603

Closed

4 tasks

jasnell closed this Aug 5, 2016

cjihrig mentioned this pull request Aug 8, 2016

v6.4.0 Release Proposal #8020

Closed

cjihrig mentioned this pull request Aug 11, 2016

v6.4.0 Proposal #8070

Merged

MylesBorins added the land-on-v4.x label Sep 9, 2016

MylesBorins mentioned this pull request Oct 26, 2016

V4.6.2 proposal #9298

Closed

Trott deleted the remark branch September 17, 2021 18:21

               The full set of trusted release keys can be imported by running:
-              ```
+              ```console

doc: use consistent markdown in README by Trott · Pull Request #7971 · nodejs/node · GitHub

Uh oh!

Uh oh!

doc: use consistent markdown in README - #7971

doc: use consistent markdown in README#7971Trott wants to merge 4 commits intonodejs:masternodejs/node:masterfrom Trott:remarkTrott/io.js:remarkCopy head branch name to clipboard

Conversation

Trott commented Aug 3, 2016

Checklist

Affected core subsystem(s)

Description of change

Uh oh!

Fishrock123 Aug 3, 2016

Choose a reason for hiding this comment

Uh oh!

Trott Aug 4, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fishrock123 Aug 4, 2016

Choose a reason for hiding this comment

Uh oh!

ChALkeR Aug 4, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Trott Aug 4, 2016

Choose a reason for hiding this comment

Uh oh!

ChALkeR Aug 4, 2016

Choose a reason for hiding this comment

Uh oh!

ChALkeR Aug 4, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ChALkeR commented Aug 4, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Trott commented Aug 4, 2016

Uh oh!

ChALkeR commented Aug 4, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Trott commented Aug 4, 2016

Uh oh!

ChALkeR commented Aug 4, 2016

Uh oh!

targos commented Aug 4, 2016

Uh oh!

jasnell commented Aug 4, 2016

Uh oh!

jasnell commented Aug 5, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

doc: use consistent markdown in README#7971
Trott wants to merge 4 commits into
nodejs:masterfrom
Trott:remark

Trott Aug 4, 2016 •
edited
Loading

ChALkeR Aug 4, 2016 •
edited
Loading

ChALkeR Aug 4, 2016 •
edited
Loading

ChALkeR commented Aug 4, 2016 •
edited
Loading

ChALkeR commented Aug 4, 2016 •
edited
Loading