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: prevent one more false-positive linkification #20087

Closed
wants to merge 1 commit into from
Closed

doc: prevent one more false-positive linkification #20087

wants to merge 1 commit into from

Conversation

vsemozhetbyt
Copy link
Contributor

@vsemozhetbyt vsemozhetbyt commented Apr 16, 2018

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

This is the same tricky case as described in #19913, I've somehow missed it then.

Too common link reference in cli.md corrupts heading from string_decoder.md in assembled all.html (markdown references seem to be case-insensitive).

Compare: stringDecoder.end([buffer]) in string_decoder.html and stringDecoder.end(buffer) in all.html with buffer parameter made mandatory and linkified.

I've checked all the headings in all.html for any additional child HTML elements except expected (code and span with # TOC links) and found only this anomaly plus nits addressed in #20086. So, for now, there are no more similar issues.

However, I do not know how we can prevent this false linkification and parameter corruption in the future. I can think of these options at least:

  • Escape all the [] in headings and demand this from now on by a rule. This may be a huge churn PR and a hard rule to follow unless added in doc linting.
  • Make a doc linting rule to compare all the link references in all docs with parameters in all headings in all docs and warn about collisions. I do not know if this is implementable and performance-safe.
  • Forbid tools/doc/html.js from adding any links to headings except for # TOC links.

cc @nodejs/documentation to consider this.

Also in passing:

  • Fix sort nit in bottom references.
  • Make the Buffer link refer to Buffer class instead of the top module heading.

@vsemozhetbyt vsemozhetbyt added the fast-track PRs that do not need to wait for 48 hours to land. label Apr 16, 2018
@nodejs-github-bot nodejs-github-bot added cli Issues and PRs related to the Node.js command line interface. doc Issues and PRs related to the documentations. labels Apr 16, 2018
@vsemozhetbyt
Copy link
Contributor Author

Please, add 👍 here to approve fast-tracking.

@vsemozhetbyt
Copy link
Contributor Author

@vsemozhetbyt
Copy link
Contributor Author

Landed in 5eb9f3c

@vsemozhetbyt vsemozhetbyt deleted the doc-fix-false-link branch April 17, 2018 01:59
vsemozhetbyt added a commit that referenced this pull request Apr 17, 2018
PR-URL: #20087
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
jasnell pushed a commit that referenced this pull request Apr 17, 2018
PR-URL: #20087
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
@vsemozhetbyt vsemozhetbyt mentioned this pull request Jul 22, 2018
2 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cli Issues and PRs related to the Node.js command line interface. 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