cabo/kramdown-rfc

doc improvement: add how to construct references to errata reports

ajeanmahoney opened this issue · 4 comments

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 commented

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 commented

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 commented

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

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