Skip to content

Preserve section links in ReSpec output #3863

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
ralfhandl opened this issue May 28, 2024 · 2 comments · Fixed by #3956
Closed

Preserve section links in ReSpec output #3863

ralfhandl opened this issue May 28, 2024 · 2 comments · Fixed by #3956
Assignees
Labels
editorial Wording and stylistic issues Housekeeping
Milestone

Comments

@ralfhandl
Copy link
Contributor

Direct links to RFC sections are useful, for example in

matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)
label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5)
form | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.
simple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.2). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.
.

Unfortunately these currently get lost when running the Markdown sources through ReSpec and result in unspecific #bib-RFC6570 links, see for example https://spec.openapis.org/oas/latest.html#style-values.

A possible solution could be to adapt the md2html processing in

if (line.indexOf('[RFC')>=0) {
line = line.replace(/\[RFC ?([0-9]{1,5})\]/g,function(match,group1){
console.warn('Fixing RFC reference',match,group1);
return '[[!RFC'+group1+']]';
});
}
and produce something like

[[RFC6570]] [section 3.2.7](https://tools.ietf.org/html/rfc6570#section-3.2.7)

that is both a bib-link and a direct link to the relevant RFC section.

@handrews handrews added the script Pull requests that update Bash or JavaScript code label May 28, 2024
@handrews
Copy link
Member

@Bellangelo this dovetails with other things you have been tackling.

@frankkilcommins
Copy link
Contributor

See OAI/Arazzo-Specification#199 for how I addressed this for Arazzo. LMK if you'd like a similar PR here.

@ralfhandl ralfhandl moved this to In Progress in Automation & Infrastructure Jul 15, 2024
@ralfhandl ralfhandl added this to the v3.0.4 milestone Jul 15, 2024
@ralfhandl ralfhandl added the editorial Wording and stylistic issues label Jul 15, 2024
@ralfhandl ralfhandl removed the script Pull requests that update Bash or JavaScript code label Jul 23, 2024
@github-project-automation github-project-automation bot moved this from In Progress to Done in Automation & Infrastructure Jul 25, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
editorial Wording and stylistic issues Housekeeping
Projects
Status: Done
Development

Successfully merging a pull request may close this issue.

4 participants