Skip to content

3.1.1: improved RFC section links #3973

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

Closed

Conversation

ralfhandl
Copy link
Contributor

@ralfhandl ralfhandl commented Jul 24, 2024

  • Link to #section-x instead of #autoid-y or #page-z
  • All RFCs are added to appendix Normative References
  • Informative reference to OpenAPI-Learn

@ralfhandl ralfhandl requested review from handrews, lornajane, miqui and a team July 24, 2024 14:29
@ralfhandl ralfhandl added the editorial Wording and stylistic issues label Jul 24, 2024
@ralfhandl ralfhandl added this to the v3.1.1 milestone Jul 24, 2024
@ralfhandl ralfhandl requested a review from mikekistler July 24, 2024 16:20
mikekistler
mikekistler previously approved these changes Jul 25, 2024
Copy link
Contributor

@mikekistler mikekistler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. 👍

@lornajane
Copy link
Contributor

I think this looks good, but I'm not sure how someone reading the markdown source can use these links. Are they just expected to know where to look for the replacements in our build scripts, or is there a better way to tackle it?

@ralfhandl
Copy link
Contributor Author

I'm not sure how someone reading the markdown source can use these links

If you mean ReSpec references like

is unrelated to [[JSON-Schema-2020-12|JSON Schema]].

then the answer unfortunately is

In this example the answer is https://www.specref.org/?q=JSON-Schema-2020-12.

Current assumption is

  • Markdown is an "editor-friendly" source format, and ReSpec references guarantee that the referenced document is automatically listed as a normative reference, or an informative if preceded by ?, and the build script will complain about mistyped SPEC-IDs
  • The "reader-friendly" end product is the respec-ified static HTML

We can keep the markdown "reader-friendly" and educate editors to (1) stick to reference patterns recognized by the build script, and (2) adjust the build script for any new external reference that is not an RFC.

Which way do we want to go?

miqui
miqui previously approved these changes Aug 1, 2024
@lornajane
Copy link
Contributor

Discussion in TDC this week, we are overall not concerned about the destination of the hyperlinks being behind another level of abstraction

@ralfhandl
Copy link
Contributor Author

Closed in favor of #3996

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
editorial Wording and stylistic issues
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants