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.
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.
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)
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!