search

ietf-tools / xml2rfc

Generate RFCs and IETF drafts from document source in XML according to the IETF xml2rfc v2 and v3 vocabularies
https://ietf-tools.github.io/xml2rfc/
BSD 3-Clause "New" or "Revised" License
64 stars 38 forks source link

Add a flag to <xref> indicating if the reference is normative #1149

Open kwatsen opened 1 month ago

kwatsen commented 1 month ago

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 for xml2rfc 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

cabo commented 1 month ago

Note that this is already fully implemented in kramdown-rfc.

kwatsen commented 1 month ago

Indeed. It's such a good idea, but all my doc sources are in XML...

rjsparks commented 1 month ago

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?

cabo commented 1 month ago

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.

rjsparks commented 1 month ago

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?

cabo commented 1 month ago

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