Doc normalize markdown reference links #29558

nschonni · 2019-09-14T18:57:28Z

Use explicit trailing [] for reference markdown links.
Escape brackets in titles that get flagged by remark-lint.
Convert old changlogs SHA links to match newer format.

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

nschonni · 2019-09-14T19:22:12Z

doc/changelogs/CHANGELOG_IOJS.md

@@ -744,7 +744,7 @@ See https://github.com/nodejs/node/labels/confirmed-bug for complete and current
 * [[`5c29c0c519`](https://github.com/nodejs/node/commit/5c29c0c519)] - **openssl**: fix keypress requirement in apps on win32 (Shigeki Ohtsu) [nodejs/node#1389](https://github.com/nodejs/node/pull/1389)
 * [[`2cd7f73d9f`](https://github.com/nodejs/node/commit/2cd7f73d9f)] - **openssl**: fix keypress requirement in apps on win32 (Shigeki Ohtsu) [nodejs/node#1389](https://github.com/nodejs/node/pull/1389)
 * [[`c65484a74d`](https://github.com/nodejs/node/commit/c65484a74d)] - **tls**: make server not use DHE in less than 1024bits (Shigeki Ohtsu) [#1739](https://github.com/nodejs/node/pull/1739)
-* [[`77f518403f`](https://github.com/nodejs/node/commit/77f518403f)] - **win,node-gyp**: make delay-load hook C89 compliant (Sharat M R) [TooTallNate/node-gyp#616](https://github.com/TooTallNa
+* [[`77f518403f`](https://github.com/nodejs/node/commit/77f518403f)] - **win,node-gyp**: make delay-load hook C89 compliant (Sharat M R) [TooTallNate/node-gyp#616](https://github.com/TooTallNate/node-gyp/pull/616)


These urls where incomplete

nschonni · 2019-09-14T19:22:31Z

doc/changelogs/CHANGELOG_IOJS.md

@@ -1128,7 +1128,7 @@ See https://github.com/nodejs/node/labels/confirmed-bug for complete and current

 * **crypto**: significantly reduced memory usage for TLS (Fedor Indutny & Сковорода Никита Андреевич) [#1529](https://github.com/nodejs/node/pull/1529)
 * **npm**: Upgrade npm to 2.9.0. See the [v2.8.4](https://github.com/npm/npm/releases/tag/v2.8.4) and [v2.9.0](https://github.com/npm/npm/releases/tag/v2.9.0) release notes for details. Summary:
-  - Add support for default author field to make `npm init -y` work without user-input (@othiym23) [npm/npm/d8eee6cf9d](https://github.com/npm/npm/commit/d8eee6cf9d2ff7aca68dfaed2de76824a3e0d9
+  - Add support for default author field to make `npm init -y` work without user-input (@othiym23) [npm/npm/d8eee6cf9d](https://github.com/npm/npm/commit/d8eee6cf9d2ff7aca68dfaed2de76824a3e0d9)


Malformed url

nschonni · 2019-09-14T19:23:45Z

doc/api/timers.md

 <!-- YAML
 added: v0.9.1
 -->

 * `callback` {Function} The function to call at the end of this turn of
-  [the Node.js Event Loop]
+  the Node.js [Event Loop][]


This wasn't matching the reference link because of the extra text

nschonni · 2019-09-14T19:25:55Z

doc/api/stream.md

-| Writing only | [`Writable`] | <code>[_write()][stream-_write]</code>, <code>[_writev()][stream-_writev]</code>, <code>[_final()][stream-_final]</code> |
-| Reading and writing | [`Duplex`] | <code>[_read()][stream-_read]</code>, <code>[_write()][stream-_write]</code>, <code>[_writev()][stream-_writev]</code>, <code>[_final()][stream-_final]</code> |
-| Operate on written data, then read the result | [`Transform`] | <code>[_transform()][stream-_transform]</code>, <code>[_flush()][stream-_flush]</code>, <code>[_final()][stream-_final]</code> |
+| Reading only | [`Readable`][] | [`_read()`][stream-_read] |


Only the changes for the "Class" column were flagged by remark-lint. Replaced the <code> for consistency

nschonni · 2019-09-14T19:27:17Z

doc/api/crypto.md

@@ -622,7 +622,7 @@ provided, `otherPublicKey` is expected to be a [`Buffer`][],
 If `outputEncoding` is given a string is returned; otherwise, a
 [`Buffer`][] is returned.

-### diffieHellman.generateKeys([encoding])
+### diffieHellman.generateKeys(\[encoding\])


These were rendering as links in the heading because of the reference link [encoding]

nschonni · 2019-09-24T19:01:20Z

@Trott I used the web to resolve the conflicts. Is there a better way to split this to make it easier for reviewers?

Trott · 2019-09-25T04:30:29Z

@Trott I used the web to resolve the conflicts. Is there a better way to split this to make it easier for reviewers?

I suppose if you want smaller change sets for easier review, you can either do one file per branch/PR or one type of change per branch/PR.

@nodejs/documentation Anyone want to review this as-is? It seems OK to me. I understand why we should escape [ and ] when they're not links. It has the minor disadvantage of making the raw markdown harder to understand. And it's a pretty big change-set (876 lines). But I definitely don't oppose it.

sam-github · 2019-09-25T18:23:30Z

I don't have a problem with the changes being across multiple files, but I am having trouble figuring out what the specific changes are, and why. I edited the description to add the commit message description in, not sure why github didn't do that itself.

For example, the unescaped [] API docs seems to be processed by our tools into HTML fine, for example, https://nodejs.org/api/tls.html#tls_tls_connect_options_callback doesn't have the raw square brackets escaped in source. So, why would we use more unreadable markup, if it doesn't change the HTML output?

Some of the changes seem to be literally malformed URLs, those could maybe be their own commit, and are obviously a good idea.

The adding of empty [] to make refs be ['some thing()'][] is in same category, if the output HTML is valid, why change the markup?

In general, we know the markup is right when the output is right, so making things "right" with no tool support to maintain that "rightness" is fragile. If we really do require these markup changes, then tool support is needed to enforce them.

It sounds like @nschonni you are relying on some kind of tools opinion about what correct markdown should be, and making the changes it suggests?

nschonni · 2019-10-01T04:42:12Z

These are flagged by remark-lint when using the "recommended" preset in addition to the current remark-node-preset, which has an upstream PR

nschonni · 2019-10-01T05:21:06Z

I've broken up the commits a little further to make it easier to review the individual types of changes

Trott · 2019-10-01T16:11:04Z

@nodejs/collaborators This could use some reviews.

BridgeAR · 2019-10-01T20:03:28Z

@vsemozhetbyt do you know how much our tooling has to fix currently to get our links to work as expected and would this improve our situation?

@nschonni I think it would be great if this PR could be split into multiple ones. That way they would probably be signed-off much faster. Especially since some parts might be more controversial to some than others. I definitely see the value in most of the change but there are a few which we might not want to change right now.

I think splitting out 3899b8c and f4f7384 would be enough, since those two seem most controversial at the moment and make up a big part of this PR.

nschonni · 2019-10-01T21:00:04Z

I'm fine with splitting it up, but I'm wondering how that's done here. Close this PR and open new PRs for each commit, or leave the first commit and submit new ones for the others?

BridgeAR · 2019-10-01T21:17:54Z

@nschonni I would roughly do the following:

# Get the latest upstream code in your fork
git checkout master
git fetch upstream
git pull upstream/master
git push origin

git checkout -b add-explicit-brackets-to-docs
git cherry-pick 3899b8c
git push -u origin add-explicit-brackets-to-docs

git checkout master
git checkout -b escape-brackets-in-docs
git cherry-pick f4f7384
git push -u origin escape-brackets-in-docs

git checkout doc--normalize-markdown-reference-links 
git rebase -i origin/master
# Here you just remove the two commits that you cherry picked earlier
git push --force-with-lease

vsemozhetbyt · 2019-10-02T01:33:06Z

@BridgeAR Unfortunately, I've lost the track of our doc tooling system since we transfer it to the unified and remark world and I cannot be of any help here( I am afraid we may have too few collaborators that grasp all the doc tooling system now.

Reference links were used in the document, but not define at the end.

It gets confused as a reference link otherwis

nschonni · 2019-10-02T04:37:02Z

OK @BridgeAR I've split this out as recommended

BridgeAR · 2019-10-02T09:02:49Z

@nschonni thanks a lot!

BridgeAR · 2019-10-02T09:07:50Z

@nschonni are you planning on including the here used rules to our doc linter as well? Without that it will be hard to prevent any of these to be reintroduced.

nschonni · 2019-10-02T13:40:42Z

They're currently re-ignored in nodejs/remark-preset-lint-node#21, but can be enabled once these land

Trott · 2019-10-02T16:48:25Z

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/3957/

Trott · 2019-10-02T19:18:09Z

Landed in 344c5c4...420d4e4

PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

Reference links were used in the document, but not define at the end. PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

It gets confused as a reference link otherwis PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

Reference links were used in the document, but not define at the end. PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

It gets confused as a reference link otherwis PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Sep 14, 2019

nschonni mentioned this pull request Sep 14, 2019

Use and extend remark-preset-lint-recommended nodejs/remark-preset-lint-node#21

Merged

nschonni commented Sep 14, 2019

View reviewed changes

Trott force-pushed the master branch from 1ecc406 to 49cf67e Compare September 17, 2019 16:50

nschonni force-pushed the doc--normalize-markdown-reference-links branch from 899413e to eb0feda Compare October 1, 2019 05:20

nschonni force-pushed the doc--normalize-markdown-reference-links branch 2 times, most recently from bfff527 to 0622d20 Compare October 1, 2019 05:30

This was referenced Oct 2, 2019

doc: add explicit bracket for markdown reference links #29808

Closed

doc: escape brackets not used as markdown reference links #29809

Closed

nschonni added 4 commits October 2, 2019 00:35

doc: complete cut off links in old changelog

10d8e41

doc: convert old changlogs SHA links to match newer format

6700171

doc: add missing reference link values

fdcd087

Reference links were used in the document, but not define at the end.

doc: add dash between SHA and PR in changelog

1720122

It gets confused as a reference link otherwis

nschonni force-pushed the doc--normalize-markdown-reference-links branch from 0622d20 to 1720122 Compare October 2, 2019 04:36

BridgeAR approved these changes Oct 2, 2019

View reviewed changes

Trott closed this Oct 2, 2019

Trott pushed a commit that referenced this pull request Oct 2, 2019

doc: complete cut off links in old changelog

b01f17b

PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

Trott pushed a commit that referenced this pull request Oct 2, 2019

doc: convert old changlogs SHA links to match newer format

4267b88

PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

Trott pushed a commit that referenced this pull request Oct 2, 2019

doc: add missing reference link values

4b505f0

Reference links were used in the document, but not define at the end. PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

Trott pushed a commit that referenced this pull request Oct 2, 2019

doc: add dash between SHA and PR in changelog

420d4e4

It gets confused as a reference link otherwis PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

nschonni deleted the doc--normalize-markdown-reference-links branch October 2, 2019 19:24

BridgeAR pushed a commit that referenced this pull request Oct 9, 2019

doc: complete cut off links in old changelog

60b1f6f

PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

BridgeAR pushed a commit that referenced this pull request Oct 9, 2019

doc: convert old changlogs SHA links to match newer format

de4652f

PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

BridgeAR pushed a commit that referenced this pull request Oct 9, 2019

doc: add missing reference link values

d1a4aa3

Reference links were used in the document, but not define at the end. PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

BridgeAR pushed a commit that referenced this pull request Oct 9, 2019

doc: add dash between SHA and PR in changelog

62370ef

It gets confused as a reference link otherwis PR-URL: #29558 Reviewed-By: Ruben Bridgewater <[email protected]>

BridgeAR mentioned this pull request Oct 10, 2019

v12.12.0 proposal #29919

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc normalize markdown reference links #29558

Doc normalize markdown reference links #29558

nschonni commented Sep 14, 2019 •

edited by sam-github

Loading

nschonni Sep 14, 2019

nschonni Sep 14, 2019

nschonni Sep 14, 2019

nschonni Sep 14, 2019

nschonni Sep 14, 2019

nschonni commented Sep 24, 2019

Trott commented Sep 25, 2019 •

edited

Loading

sam-github commented Sep 25, 2019 •

edited

Loading

nschonni commented Oct 1, 2019

nschonni commented Oct 1, 2019

Trott commented Oct 1, 2019

BridgeAR commented Oct 1, 2019

nschonni commented Oct 1, 2019

BridgeAR commented Oct 1, 2019 •

edited

Loading

vsemozhetbyt commented Oct 2, 2019

nschonni commented Oct 2, 2019

BridgeAR commented Oct 2, 2019

BridgeAR commented Oct 2, 2019

nschonni commented Oct 2, 2019

Trott commented Oct 2, 2019

Trott commented Oct 2, 2019

Doc normalize markdown reference links #29558

Doc normalize markdown reference links #29558

Conversation

nschonni commented Sep 14, 2019 • edited by sam-github Loading

Checklist

nschonni Sep 14, 2019

Choose a reason for hiding this comment

nschonni Sep 14, 2019

Choose a reason for hiding this comment

nschonni Sep 14, 2019

Choose a reason for hiding this comment

nschonni Sep 14, 2019

Choose a reason for hiding this comment

nschonni Sep 14, 2019

Choose a reason for hiding this comment

nschonni commented Sep 24, 2019

Trott commented Sep 25, 2019 • edited Loading

sam-github commented Sep 25, 2019 • edited Loading

nschonni commented Oct 1, 2019

nschonni commented Oct 1, 2019

Trott commented Oct 1, 2019

BridgeAR commented Oct 1, 2019

nschonni commented Oct 1, 2019

BridgeAR commented Oct 1, 2019 • edited Loading

vsemozhetbyt commented Oct 2, 2019

nschonni commented Oct 2, 2019

BridgeAR commented Oct 2, 2019

BridgeAR commented Oct 2, 2019

nschonni commented Oct 2, 2019

Trott commented Oct 2, 2019

Trott commented Oct 2, 2019

nschonni commented Sep 14, 2019 •

edited by sam-github

Loading

Trott commented Sep 25, 2019 •

edited

Loading

sam-github commented Sep 25, 2019 •

edited

Loading

BridgeAR commented Oct 1, 2019 •

edited

Loading