xml2rfc
xml2rfc copied to clipboard
ietf-tools
section-number citation for reference entry that uses "<referencegroup> yields error
keyword_referencegroup type_defect | by [email protected]
A section-number citation for a reference entry that uses "<referencegroup> yields this error:
rfc9000-referencegroup-issue.xml(3876): Error: Expected the target of an <xref> with a section= attribute to be a <reference>, found <referencegroup>
Not creating output file due to errors (see above)
Unable to complete processing rfc9000-referencegroup-issue.xml
Please see the "No error if you remove ..." comment in
<https://www.rfc-editor.org/v3test/rfc9000-referencegroup-issue.xml>
Issue migrated from trac:639 at 2022-02-08 07:15:22 +0000
@[email protected] commented
Possible workaround for single RFC BCPs.
as defined in BCP<whatever> (See RFC<the only one in the bcp> section <whatever>).
Adding the XML here because it was lost in the migration from svn to GitHub.
The following construction causes the error shown above:
QUIC endpoints using PMTUD <bcp14>SHOULD</bcp14> validate ICMP
messages to protect from packet injection as specified in
<xref target="RFC8201" format="default"/>
and <xref section="5.2" sectionFormat="of" target="BCP145" format="default"/>.
There is no error if you remove the 'section="5.2" sectionFormat="of"' from the xref:
ICMP message validation <bcp14>MUST</bcp14> include matching
IP addresses and UDP ports <xref target="BCP145" format="default"/> and...
Note that the BCP mentioned in this issue has only one RFC in it (as of Jan 2024).
A solution that covers the general case of multiple RFCs in the subseries would need both a style recommendation and a way to specify it in the XML.
Perhaps:
As specified in Section 4 of RFC 8719 [BCP226]
Section 4 of RFC 8719 would be a link to that section. [BCP226] would take the reader to the reference entry.
The XML to construct might like this (the name of the attribute to capture which RFC is being linked to is just a suggestion):
<xref section="4" sectionFormat="of" rfcTarget="RFC8719" target="BCP145" format="default"/>
There would need to be a check that the RFC exists in the subseries to catch typos.
Ah. We solved that in RFC 9485 by having two references, one for the section reference, one for the BCP/STD (the latter of which is still impacted by #1067).
Section <xref target="RFC3629" section="10" sectionFormat="bare" format="default" derivedLink="https://rfc-editor.org/rfc/rfc3629#section-10" derivedContent="RFC3629"> "Security Considerations"</xref> of RFC 3629 <xref target="STD63" format="default" sectionFormat="of" derivedContent="STD63"/>
There even is syntax for this in kramdown-rfc now (https://mailarchive.ietf.org/arch/msg/rfc-markdown/XZQ5f7YHQJ58e7sUfGHBWJ14xe8). Is there a need to add something to RFCXML?
@cabo
Is there a need to add something to RFCXML?
I'm not sure it's necessary. It would be nice to have a more elegant way to construct the xref than the workaround above.
Tools hat off for a moment. If you are referencing a section of an RFC, what is the value of compounding what you've written with the complication the the RFC happens to be (in) an subseries. Such a concept might well better be handled in prose, and leave the reference to be concrete, to the RFC, not the container.
Can this problem be explored with an example of a referencegroup that's not trying to model subseries to make sure the pecularities of subseries aren't hiding something we should be considering?
I think we have converged on making the reference to the section in the RFC in the STD/BCP. The compounding happens because the RFC is no longer labeled in the rendering we have chosen for referencegroups. But there is a reasonable way to handle this, as shown in RFC 9485.