Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: sort bottom-of-file markdown links #24679

Closed
wants to merge 1 commit into from

Conversation

sam-github
Copy link
Contributor

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
Copy link
Collaborator

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

@sam-github
Copy link
Contributor Author

@vsemozhetbyt
Copy link
Contributor

vsemozhetbyt commented Nov 27, 2018

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
Copy link
Contributor Author

@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
Copy link
Contributor Author

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
Copy link
Contributor

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
Copy link
Contributor

vsemozhetbyt commented Nov 27, 2018

Should I wait for resorting in the backporting PRs?

@sam-github
Copy link
Contributor Author

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
Copy link
Contributor

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

@vsemozhetbyt
Copy link
Contributor

It seems this need rebasing to run CI.

sam-github added a commit to sam-github/node that referenced this pull request Nov 28, 2018
@sam-github
Copy link
Contributor Author

PTAL

@vsemozhetbyt
Copy link
Contributor

@vsemozhetbyt
Copy link
Contributor

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

@sam-github
Copy link
Contributor Author

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

doc/api/fs.md Outdated Show resolved Hide resolved
Reapply nodejs#12726

It would be nice to have the sort check applied as part of doc testing,
but this change doesn't implement that.
@Trott Trott closed this Nov 28, 2018
rvagg pushed a commit that referenced this pull request Dec 1, 2018
Backport of #24679

PR-URL: #24682
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
sam-github added a commit to sam-github/node that referenced this pull request Dec 3, 2018
Backport-PR-URL: nodejs#24680
PR-URL: nodejs#24679
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
BridgeAR pushed a commit that referenced this pull request Dec 5, 2018
Backport-PR-URL: #24680
PR-URL: #24679
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
@BridgeAR BridgeAR mentioned this pull request Dec 5, 2018
4 tasks
sam-github added a commit to sam-github/node that referenced this pull request Dec 17, 2018
MylesBorins pushed a commit that referenced this pull request Dec 21, 2018
Reapply #12726

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

Backport-PR-URL: #24681
PR-URL: #24679
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
MylesBorins pushed a commit that referenced this pull request Dec 26, 2018
Reapply #12726

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

Backport-PR-URL: #24681
PR-URL: #24679
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
@codebytere codebytere mentioned this pull request Jan 4, 2019
refack pushed a commit to refack/node that referenced this pull request Jan 14, 2019
Reapply nodejs#12726

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

PR-URL: nodejs#24679
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
@sam-github sam-github deleted the resort-markdown-refs branch March 20, 2019 15:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
author ready PRs that have at least one approval, no pending requests for changes, and a CI started. doc Issues and PRs related to the documentations. fast-track PRs that do not need to wait for 48 hours to land.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants