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 improvement: add how to construct references to errata reports #221

Open
ajeanmahoney opened this issue Jan 9, 2024 · 4 comments
Open

Comments

@ajeanmahoney
Copy link
Contributor

ajeanmahoney commented Jan 9, 2024

In RFCXML, a reference to an errata report is constructed like the following to match the Web Portion of the Style Guide:

<reference anchor="Err1912" quote-title="false" target="https://www.rfc-editor.org/errata/eid1912"> 
   <front> 
      <title>Erratum ID 1912</title>
      <author>
         <organization>RFC Errata</organization>
      </author> 
   </front> 
   <refcontent>RFC 2978</refcontent>
</reference>

Which I think in kramdown-rfc would be specified as:

  Err1912:
    target: https://www.rfc-editor.org/errata/eid1912
    title: Erratum ID 1912
    author:
    - org: RFC Errata
    refcontent: RFC 4880
    date: false

with the caveat that title quotes are not suppressible yet (#182).

Note that refcontent rather than seriesInfo should be used to capture the RFC number (an erratum is not part of the RFC Series).

I'd be happy to create the PR myself, but I wanted to make sure I had the construction correct first.

@cabo
Copy link
Owner

cabo commented Jan 9, 2024

Nice! I have struggled with this. Essentially I'd like to have a fixed anchor syntax like Err1912.4880 that can be processed like other anchor syntaxes like RFCnnnnn or IANA.rrrrrrrrr can be.

@cabo
Copy link
Owner

cabo commented Jan 10, 2024

So for now I have fixed #182 (see comment there for usage).
Next: Generating all the boilerplate automatically.
I think I'll settle on

Err1912:
  refcontent: RFC 4880

(And then document that)

@cabo
Copy link
Owner

cabo commented Jan 10, 2024

Maybe you can, in parallel, replace "Erratum ID" by "Errata Report" (not every Errata Report is actually an Erratum).

@ajeanmahoney
Copy link
Contributor Author

Added an issue to the Style Guide (rfc-editor/draft-rpc-rfc7322bis#33) to update the terminology, thanks!

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

No branches or pull requests

2 participants