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
63 stars 35 forks source link

Synthesized References Section does not get an anchor assigned #1133

Closed cabo closed 6 days ago

cabo commented 1 week ago

Describe the issue

xml2rfc sometimes synthesizes a References section around the informative and normative References sections. This section does not receive an anchor, so it cannot be referenced in an <xref

Code of Conduct

cabo commented 1 week ago

It appears that this is done in element_back in v2v3.py

kesara commented 1 week ago

@cabo, Do you have an example? Thanks.

cabo commented 1 week ago

Sure. https://www.ietf.org/archive/id/draft-ietf-cbor-edn-e-ref-00.xml has:

  <back>
    <references>
      <name>References</name>
      <references anchor="sec-normative-references">
        <name>Normative References</name>

the inner section Normative References has an anchor (as provided by kramdown-rfc), the outer Reference does not.

Input to v2v3.py: draft-ietf-cbor-edn-e-ref.xml.txt

Maybe I should do the joining together into one section in kramdown-rfc already.

kesara commented 6 days ago

@cabo, Are you referring to the lack of an anchor attribute in the <references> tag just after the <back> tag?

The anchor is an optional attribute for <references>. So, I think it's okay to skip adding an artificial anchor.

For historical reasons, v2v3 converter encapsulates all <references> into a single <references> ^1.

cabo commented 6 days ago

Well, the XML generated is valid; it just leads to text like the below:

https://cbor-wg.github.io/edn-literal/close-42/draft-ietf-cbor-edn-literals.html#name-structure-of-this-document

There is no way to reference Section 6, so the text separately references Section 6.1 and 6.2.

If the v2v3 behavior to synthesize a top-level References section is here to stay, I could simply preempt that behavior in kramdown-rfc and apply an anchor there.

kesara commented 6 days ago

I don't know the reason why v2v3 encapsulates multiple <references> into single <references>. But I would assume it would be an undesirable change now since the xml2rfc v2v3 converter has behaved that way for many years, so better to preempt that behavior in kramdown-rfc?

cabo commented 6 days ago

Done in https://github.com/cabo/kramdown-rfc/commit/98ff1bd

(I'm not going to make a new release now right before the I-D deadline, so this will be in 1.8.1 on July 9)

cabo commented 6 days ago

Thanks for the feedback!