Open kwatsen opened 1 month ago
Note that this is already fully implemented in kramdown-rfc.
Indeed. It's such a good idea, but all my doc sources are in XML...
and changes to the xml (at least for RFCs) is owned by RSWG now - not something we can easily just start changing in xml2rfc.
Also Carsten - please remind me (or other people who stumble across this) what the kramdown-rfc implementation of this looks like? I don't think I've seen the nature of the reference indicated each time the reference is used before?
Robert, you can list the references in the YAML header (and make the normative/informative distinction there). That's what most people do, when it makes sense to think about references globally for the document.
You also can do a reference that is completely inline, as in {{!RFC8949}} or {{?RFC9423}} -- this is sorted into the data that is in the YAML header, with ! indicating normative and ? indicating informative. This makes sense if the reference is of local interest only and you can make the determination there.
So the first version (in the YAML) is structurally the same as putting the references in the informal or normative reference section in the xml. It's not what Kent is asking for.
It the second - the completely inline version that has the property he's looking for, but - does kramdown-rfc error or warn or anything if someone has both {{!RFC8949}} and {{?RFC8949}} inline in different places, add the document to both reference sections, or follow some "highest value seen wins" algorithm like what Kent proposes?
So the first version (in the YAML) is structurally the same as putting the references in the informal or normative reference section in the xml. It's not what Kent is asking for.
Correct. I just mentioned it because it is the more popular way of handling this.
It the second - the completely inline version that has the property he's looking for, but - does kramdown-rfc error or warn or anything if someone has both {{!RFC8949}} and {{?RFC8949}} inline in different places, add the document to both reference sections, or follow some "highest value seen wins" algorithm like what Kent proposes?
The reference is treated as normative if at least one of the citations has a “!”. (Which makes sense: Any normative reference may have additional informative [or normative] citations and still stays a normative reference.)
Grüße, Carsten
Description
It is sometimes difficult for authors to track if a reference is normative of not. This is especially true after a reference is used multiple times.
For instance, the first time a reference added, it may be Informative but, later, a Normative reference is made to the same reference. The second use will not cause a missing-reference error, since it is already present, but it continues to be in the "Informative" section, though it should be moved to the "Normative" section.
It would be nice if, on a per
<xref>
basis, a flag could be set to indicate that the reference is Normative, and then forxml2rfc
to autogenerate the Normative/Informative sections, or at least validate that they are accurate.The rule would be: a reference is Normative if there is at least one Normative use, and Informative otherwise.
Code of Conduct