doc: prepare miscellaneous docs for new markdown lint rules

[Trott]

Prepare the final few documents that haven't been updated to always use
[] with reference links and to escape [ and ] for things that
aren't links in markdown files.

These are the final changes required before we can use the next version of remark-preset-lint-node.

@nschonni @nodejs/documentation

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[Trott]

Collaborators, please 👍 here to fast-track.

[Trott]

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

[nschonni]

Think the reference link might need to be updated instead for the 3 in this section to include the array modifier in the identifier

[nschonni]

The current way does work though

[Trott]

My thinking in preferring this way is that the linked info is not about ArrayBufferView[]. It's about ArrayBufferView. So the link text reflects that.

[XhmikosR]

Escaping the square brackets is not needed AFAICT. Which tool complains?

EDIT: For example, this shows just fine without escaping [ https://github.com/nodejs/node/tree/master/benchmark#createbenchmarkfn-configs-options

[Trott]

Escaping the square brackets is not needed AFAICT. Which tool complains?

EDIT: For example, this shows just fine without escaping [ https://github.com/nodejs/node/tree/master/benchmark#createbenchmarkfn-configs-options

It makes the text a link (without displaying brackets at all) if the text happens to match a bottom-reference, which it did in one case that @nschonni found. So it only causes problems infrequently. Or at least that's my understanding. Maybe @nschonni can confirm/clarify.

[nschonni]

The instance this did flag correctly was #29809 (comment) and the rule that flags it is https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-undefined-references

[Trott]

The instance this did flag correctly was #29809 (comment) and the rule that flags it is https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-undefined-references

And in the current version of the docs (for 12.12.0), you can see the problem: https://nodejs.org/dist/latest-v12.x/docs/api/crypto.html#crypto_diffiehellman_generatekeys_encoding

The brackets are gone and "encoding" is now link text.

[nschonni]

From the upstream build failure, there are a few new ones in doc/api/vm.md

tmp/doc/api/vm.md
  315:28-315:45  warning  Found reference to undefined definition               no-undefined-references     remark-lint
  565:46-565:57  warning  Use the trailing [] on reference links                no-shortcut-reference-link  remark-lint
  565:46-565:57  warning  Found reference to undefined definition               no-undefined-references     remark-lint
  656:70-656:81  warning  Use the trailing [] on reference links                no-shortcut-reference-link  remark-lint
  656:70-656:81  warning  Found reference to undefined definition               no-undefined-references     remark-lint

[Trott]

From the upstream build failure, there are a few new ones in doc/api/vm.md

tmp/doc/api/vm.md
  315:28-315:45  warning  Found reference to undefined definition               no-undefined-references     remark-lint
  565:46-565:57  warning  Use the trailing [] on reference links                no-shortcut-reference-link  remark-lint
  565:46-565:57  warning  Found reference to undefined definition               no-undefined-references     remark-lint
  656:70-656:81  warning  Use the trailing [] on reference links                no-shortcut-reference-link  remark-lint
  656:70-656:81  warning  Found reference to undefined definition               no-undefined-references     remark-lint

Good to know. I'm OK with fixing those up when the lint rule lands on master, just as long as there's three lines to fix and not 150.

[XhmikosR]

It's no big deal, I'm just trying to understand why perfectly fine square brackets are flagged. Are the docs being built here on CI? Is the output the same?

[Trott]

It's no big deal, I'm just trying to understand why perfectly fine square brackets are flagged. Are the docs being built here on CI? Is the output the same?

Docs are built on CI so that if any changes to the docs happen that break doctool or whatever, we know. I don't think that output is checked, but I don't have any reason to believe it's different than when people run locally.

[Trott]

Landed in ed5eaa0