xml2rfc updates

[opoudjis]

Just stumbled in https://greenbytes.de/tech/webdav/draft-iab-rfc7991bis-latest.html, which presumably supersedes Levkowetz's addenda to RFC 7991. draft-levkowetz-xml2rfc-v3-implementation-notes is also being updated.

Will need to implement any new features.

Not in a rush: xml2rfc v3 is still clearly in experimental stage.

[opoudjis]

Include: https://xml2rfc.tools.ietf.org/xml2rfc-doc.html

[opoudjis]

The authoritative reference is now:

• https://authors.ietf.org/rfcxml-vocabulary
• https://datatracker.ietf.org/doc/draft-iab-rfc7991bis/04/
• https://greenbytes.de/tech/webdav/draft-iab-rfc7991bis-latest.html = 7991bis-05 has just been submitted, and I will be including updates from there where they are not disruptive.

[opoudjis]

Some of these updates have already been actioned:

7991 to 7991bis-04 (April 2022)

• Allow <blockquote> as a child of <aside> and <li>.
• Removed "It is an error to have both a "src" attribute and content in the <artwork> element." from Section 2.6.6.
• Added <toc> element
• Added <u> element.
• Changed the "hanging" attribute of <dl> to "newline".
• Added the "indent" attribute to <dl>.
• Added the "align" attribute to <table>. Made the table title centered under the table.
• The <name> element now allows many more elements inside of it.
• Redefined <references> to allow <references> within it. In the typical case, an outer <references> will be used to hold an inner <references> for normative references and an inner <references> to hold informative references.
• Un-deprecated metadata attributes on the <rfc> element (with the intent to restore v2 semantics of <seriesInfo> as well).
• Added <contact> element.
• Allowed multiple <email> elements in <address>.
• Added "markers" attribute to <sourcecode> element.
• Added "brackets" attribute to <eref> element.

7991bis-04 to 7991bis-05 (Dec 2023)

• add editorial stream

[opoudjis]

So to action:

• Removed "It is an error to have both a "src" attribute and content in the <artwork> element." from Section 2.6.6.
• Added <toc> element
• The <name> element now allows many more elements inside of it.
• Un-deprecated metadata attributes on the <rfc> element (with the intent to restore v2 semantics of <seriesInfo> as well).
• Added <contact> element.
• Allowed multiple <email> elements in <address>.
• Added "brackets" attribute to <eref> element.
• add editorial stream

[opoudjis]

• Removed "It is an error to have both a "src" attribute and content in the <artwork> element."

Metanorma doesn't have any provision for src attributes on pre, not adding it for this.

• Added <toc> element

The toc element is generated by the preptool, so it must not be provided by Metanorma.

• The <name> element now allows many more elements inside of it.

The additions are: bcp, br, em, iref, strong, sub, sup. These were always permitted by Metanorma, and if anything we would have had to remove them previously in postprocessing, which we have not done. Nothing needs to be done.

• Un-deprecated metadata attributes on the <rfc> element

We never truly got rid of them.

• Allowed multiple <email> elements in <address>.

Done.

[opoudjis]

• Added "brackets" attribute to <eref> element.

Determines whether the formatter should automatically enclose the URI in angle brackets ("angle") or not (default of "none").

Implementing this would require a style attribute on link in Metanorma, to be entered as a style=angle% prefix on the link contents, as we have done for xrefs. I can see that that is not an unreasonable expectation on links, which are rendered similarly to cross-references. Adding to standoc, though it will only do anything in IETF.

[opoudjis]

Can't use style=angle%, since Asciidoctor's native parser already processes style=...., and expects it to follow a comma delimiter: http://example.com[style=brackets], http://example.com[Text,style=brackets].

[opoudjis]

I declined to implement contact in 2021, #161 (comment), and I still think the element is very hard to justify; in any case, it can always be hard-coded into the document as a passthrough instance, which is how we've handled u.

[opoudjis]

"editorial" stream has been made legal, but the stream is specified as open-ended text in :submission-type:

[opoudjis]

Of the other changes to RFC 7991 listed in the RFC 7991bis-05 change log, we do not support the following:

• artset, and I don't see a strong reason to.
• reference/@quoteTitle
• We do not support referencegroup, so we do not support referencegroup/@target or referencegroup/seriesInfo
• postal/cityarea, postal/extaddr, postal/pobox, postal/sortingcode, but these have been marked as deprecated anyway
• reference/stream, as the stream of an IETF document
• author/@anchor or contact/@anchor
• section/author
• ol/@indent, t/@indent (we support dl/@indent)
• li/@bare, li/@empty, li/@indent
• ul/@bare, ul/@indent
• xref/@section, xref/@sectionFormat
• nested sup and sub (asciidoctor does not support these)

[opoudjis]

I am not going to implement the following:

• artset: much too convoluted to realise, and not convinced it is necessary in well-laid out documents.
• reference/@quoteTitle: whether the title of a reference is quoted or not is not an idiosyncratic requirement, it is governed by the relaton-render stylesheet. The spec suggests "This can be used to prevent quoting, such as on errata." I don't know what that would even look like, but it does not sound like a good idea...
• postal/cityarea, postal/extaddr, postal/pobox, postal/sortingcode, as these have been marked as deprecated anyway
• section/author, for the same reason I declined to realise contact: this is semantic markup wedged into presentation awkwardly
• nested sup and sub (asciidoctor does not support these)
• li/@bare, li/@empty, li/@indent (seems to be error in addenda)

I will implement the following:

• referencegroup, for references that include other references via relation=includes
• reference/stream, as the stream of an IETF document
• author/@anchor (will just be a dynamically generated GUID)
• ol/@indent, t/@indent (we already support dl/@indent)
• ul/@bare, ul/@indent
• xref/@section, xref/@sectionFormat (these are taken across from relref, which is now deprecated)

[opoudjis]

Implemented referencegroup, but will need relaton-ietf to complete the included bibitem records.

[opoudjis]

Not supporting xref/@format, I think it overkill.

[opoudjis]

A BCP 9 reference is being generated from Metanorma input:

[bibliography]
== Bibliography
* [[[a,IETF BCP 9]]]

as

   [a]        "The Internet Standards Process - Revision 3", BCP 9, RFC
              2026, IETF.

              "Guidance on Interoperation and Implementation Reports for
              Advancement to Draft Standard", BCP 9, RFC 5657, IETF.

              "Reducing the Standards Track to Two Maturity Levels",
              BCP 9, RFC 6410, IETF.

              "Retirement of the "Internet Official Protocol Standards"
              Summary Document", BCP 9, RFC 7100, IETF.

              "Characterization of Proposed Standards", BCP 9, RFC 7127,
              IETF.

              "Increasing the Number of Area Directors in an IETF Area",
              BCP 9, RFC 7475, IETF.

              "IETF Stream Documents Require IETF Rough Consensus",
              BCP 9, RFC 8789, IETF.

              "Responsibility Change for the RFC Series", BCP 9, RFC
              9282, IETF.

              <https://www.rfc-editor.org/info/bcp9>

The inserted "BCP 9" is happening because it is, after all, a document identifier, but it is redundant, and I'm reopening #95 to get rid of it. The output should be just:

   [a]        "The Internet Standards Process - Revision 3", RFC
              2026, IETF.

              "Guidance on Interoperation and Implementation Reports for
              Advancement to Draft Standard",  RFC 5657, IETF.

              "Reducing the Standards Track to Two Maturity Levels",
              RFC 6410, IETF.

              "Retirement of the "Internet Official Protocol Standards"
              Summary Document", RFC 7100, IETF.

              "Characterization of Proposed Standards", RFC 7127,
              IETF.

              "Increasing the Number of Area Directors in an IETF Area",
              RFC 7475, IETF.

              "IETF Stream Documents Require IETF Rough Consensus",
               RFC 8789, IETF.

              "Responsibility Change for the RFC Series", RFC
              9282, IETF.

              <https://www.rfc-editor.org/info/bcp9>

[opoudjis]

As @rjsparks has pointed out in relaton/relaton-ietf#120 , with reference to ietf-tools/xml2rfc#1067 , need to restore the seemingly extraneous BCP identifier, and insert authors, DOIs, dates, and URLs.

The model is

[STD69]    Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
              STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009,
              <https://www.rfc-editor.org/info/rfc5730>.

              Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Domain Name Mapping", STD 69, RFC 5731, 
              DOI 10.17487/RFC5731, August 2009,
              <https://www.rfc-editor.org/info/rfc5731>.

              Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Host Mapping", STD 69, RFC 5732, DOI 10.17487/RFC5732, 
              August 2009, 
              <https://www.rfc-editor.org/info/rfc5732>.

              Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Contact Mapping", STD 69, RFC 5733, 
              DOI 10.17487/RFC5733, August 2009, 
              <https://www.rfc-editor.org/info/rfc5733>.

              Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Transport over TCP", STD 69, RFC 5734, 
              DOI 10.17487/RFC5734, August 2009, 
              <https://www.rfc-editor.org/info/rfc5734>.

              <https://www.rfc-editor.org/info/std69>

[opoudjis]

I am now getting:

   [a]        Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
              BCP 69, RFC 5730, IETF, August 2009.

              Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Domain Name Mapping", BCP 69, RFC 5731, IETF, August 2009.

              Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Host Mapping", BCP 69, RFC 5732, IETF, August 2009.

              Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Contact Mapping", BCP 69, RFC 5733, IETF, August 2009.

              Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Transport over TCP", BCP 69, RFC 5734, IETF, August 2009.

              <https://www.rfc-editor.org/info/std69>

The DOI and links are in the RFC XML, they are being suppressed by the existing version of xml2rfc. The "IETF" is the stream element, which has been a recent addition to XML RFC. IMO, the fact that it's being output by xml2rfc is also an xml2rfc issue: it is not inaccurate to indicate the stream of the included documents.

I am deeming this task satisfied. Apart from undoing the removal of the BCP/STD identifier, the only changes were to put the URL for the reference on the reference element as well as the format element; and to fix included author rendering, processing included works recursively for rendering.

[rjsparks]

Be sure to follow what unfolds at ietf-tools/xml2rfc#1097, and reopen this if necessary.

[opoudjis]

Yes, I did note the existence of that issue with dismay :)