doc: sort bottom-of-file markdown links

[sam-github]

Reapply #12726

It would be nice to have the sort check applied as part of doc testing,
but this change doesn't implement that.

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

[nodejs-github-bot]

@sam-github sadly an error occured when I tried to trigger a build :(

[sam-github]

This won't land on 11, 10, 8, so I prepared backports immediately, see:

• [v11.x backport] doc: sort bottom-of-file markdown links #24680
• [v10.x backport] doc: sort bottom-of-file markdown links #24681
• [v8.x backport] doc: sort bottom-of-file markdown links #24682

[vsemozhetbyt]

We still have one inconsistency. In ASCII the order is: A-Z (upper case), ` (backtick), a-z (lower case). And we conform inside lines, even when it does not seem completely intuitively right (not as in dictionaries):

[`DeflateRaw`]: #zlib_class_zlib_deflateraw
[`Deflate`]: #zlib_class_zlib_deflate

However, as for the first symbol, some documents have upper case letters before backticks (i.e.
consistently):

[Using `options.selectPadding()`]: #http2_using_options_selectpadding
[`'checkContinue'`]: #http2_event_checkcontinue

some documents have upper case letters after backtick (i.e. not consistently):

[`strict mode`]: #assert_strict_mode
[Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison

[sam-github]

@vsemozhetbyt I didn't try to fix all inconsistencies, my goal was to make it locally consistent. There was a fair number of unsorted-by-any-algorithm positions.

Maybe that's a mistake. I would personally prefer to have strict ordering according to the default "C"/Posix locale -- which is ASCII ordering. Entirely ASCII makes it much faster to pass the entire block through programmer's editor's sort command, but IIRC from my first crack at this, existing usage had the backtick docs before all others, so I kept that in order to minimize churn.

[sam-github]

Btw, I'm willing to go through and resort all the open sorting PRs, time consuming though it is, but only if I know they will be rubber stamped.

[vsemozhetbyt]

If you mean the backport PRs, they still have no reviews, but I plan to review them. And I usually compare automatically-sorted-in-editor lists with your variants when the diff is big)

[vsemozhetbyt]

Should I wait for resorting in the backporting PRs?

[sam-github]

Should you wait? I don't know. If you are OK with this one landing, then yes, go ahead and review the others so they can all land at about the same time.

None of them are backports in the sense that I didn't use git to make them, there are too many differences between branches. I went through and sorted doc/api/*.md with my editor for all the branches to make sure they all end up in the same state, on all branches.

I think the current set of PRs makes all the files locally consistent, which isn't just cosmetic. Its sort of a flag day... any commits landing on master after this that touch the markdown refs will have trouble cherry-picking back to the branches, unless those branches are already sorted.

It would be really nice to have a markdown test tool that enforced ordering.

[vsemozhetbyt]

I am OK with this one landing as is. I will try to review the others tomorrow.

[vsemozhetbyt]

It seems this need rebasing to run CI.

[sam-github]

PTAL

[vsemozhetbyt]

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

[vsemozhetbyt]

Node.js Collaborators, please, add 👍 here if you approve fast-tracking.

[sam-github]

I'd like to fast-track to avoid conflicts.