doc: use consistent markdown in README #7971

Trott · 2016-08-03T23:36:02Z

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.

Fishrock123 · 2016-08-03T23:45:03Z

README.md


-```
+```shell


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 «$».

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

ChALkeR · 2016-08-04T02:29:02Z

README.md

 $ curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt
 ```

 To check that a downloaded file matches the checksum, run
 it through `sha256sum` with a command such as:

-```
+```shell


ChALkeR · 2016-08-04T02:37:52Z

README.md


 The full set of trusted release keys can be imported by running:

-```
+```console


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.

ChALkeR · 2016-08-04T03:25:04Z

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

Trott · 2016-08-04T03:31:22Z

@ChALkeR Switched that one instance to shell. Thanks.

ChALkeR · 2016-08-04T03:35:14Z

@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

Trott · 2016-08-04T03:40:53Z

@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?

ChALkeR · 2016-08-04T04:03:54Z

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

targos · 2016-08-04T04:49:28Z

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

jasnell · 2016-08-04T06:15:40Z

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 <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: James M Snell <[email protected]>

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: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: James M Snell <[email protected]>

jasnell · 2016-08-05T19:33:09Z

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 <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: James M Snell <[email protected]>

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: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: James M Snell <[email protected]>

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: use consistent markdown in README #7971

doc: use consistent markdown in README #7971

Trott commented Aug 3, 2016

Fishrock123 Aug 3, 2016

Trott Aug 4, 2016 •

edited

Loading

Fishrock123 Aug 4, 2016

ChALkeR Aug 4, 2016 •

edited

Loading

Trott Aug 4, 2016

ChALkeR Aug 4, 2016

ChALkeR Aug 4, 2016 •

edited

Loading

ChALkeR commented Aug 4, 2016 •

edited

Loading

Trott commented Aug 4, 2016

ChALkeR commented Aug 4, 2016 •

edited

Loading

Trott commented Aug 4, 2016

ChALkeR commented Aug 4, 2016

targos commented Aug 4, 2016

jasnell commented Aug 4, 2016

jasnell commented Aug 5, 2016


		```
		```shell

doc: use consistent markdown in README #7971

doc: use consistent markdown in README #7971

Conversation

Trott commented Aug 3, 2016

Checklist

Affected core subsystem(s)

Description of change

Fishrock123 Aug 3, 2016

Choose a reason for hiding this comment

Trott Aug 4, 2016 • edited Loading

Choose a reason for hiding this comment

Fishrock123 Aug 4, 2016

Choose a reason for hiding this comment

ChALkeR Aug 4, 2016 • edited Loading

Choose a reason for hiding this comment

Trott Aug 4, 2016

Choose a reason for hiding this comment

ChALkeR Aug 4, 2016

Choose a reason for hiding this comment

ChALkeR Aug 4, 2016 • edited Loading

Choose a reason for hiding this comment

ChALkeR commented Aug 4, 2016 • edited Loading

Trott commented Aug 4, 2016

ChALkeR commented Aug 4, 2016 • edited Loading

Trott commented Aug 4, 2016

ChALkeR commented Aug 4, 2016

targos commented Aug 4, 2016

jasnell commented Aug 4, 2016

jasnell commented Aug 5, 2016

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