[Rfc-markdown] 1.4.7..1.4.10: More section reference support, BCP/STD references

[Carsten Bormann <[e-mail]>]

A few more v3 additions (again, mostly thanks to Martin Thomson):

# Allow !?- in section references

One could always write {{?RFC1149}} to add an informative reference, or {{!RFC8610}} for a normative reference, without needing to touch the YAML metadata.  Also, with YAML metadata of the form...

normative:
  RFC8610: cddl

...one could write {{-cddl}} to have an indirection to painlessly move to a revised RFC without updating all references in the text.

New in 1.4.10: All three syntaxes are now available for Section references as well:

> The Extended Diagnostic Notation is defined in {{Appendix G of !RFC8610}}.


# Handle Sections+Appendices, enable (markdown specified) link text in xref

Section References have been further enhanced; you can now write monsters such as:

> This uses the definitions in {{Sections 1 (Introduction), 2 (The Style of Data Structure Specification), and 3 (Syntax) and Appendices B (ABNF) and G (Extended Diagnostic Notation) of !RFC8610 (CDDL)}}.

(The error handling is a but crusty, though, and you can’t have a comma before the “and Appendices".)
The text in parentheses becomes link text (which is not special in TXT format).

Result in TXT is a bit boring:
   This uses the definitions in Sections 1 (Introduction), 2 (The Style
   of Data Structure Specification), and 3 (Syntax) and Appendices B
   (ABNF) and G (Extended Diagnostic Notation) of CDDL [RFC8610].
The HTML has all the links.
(I have copied the XML below (*) for your amusement…  
You will be excused if you try to write this by hand and make a mistake.)

The text snippets in parentheses can use markdown, but there is a bit xml2rfc cruftiness (**) in the way before that can be fully used.

# Enable BCP and STD references 

{{STD0094}} or {{?BCP190}} etc.

A little limitation is that you need to be consistent with the leading zeroes; you can’t have {{STD94}} and {{STD0094}} in the same document.

This feature is based on an experimental bibxml server that may or may not always be available.
If that is a problem, or you want to support offline use, a new (rather slow) command…

kramdown-rfc-cache-subseries-bibxml

…can be used to build a local cache that is equivalent to the content of that server (stored in you xml2rfc/kramdown-rfc cache directory such as ~/.cache/xml2rfc).
(The command does not use the experimental server but goes directly to the sources, so it is a bit slow particularly when filling the cache.  Couple of minutes…)


As usual, update with

  gem update
or, more specifically
  gem update kramdown-rfc2629

Please keep the feedback (***) flowing!

Grüße, Carsten

(*)
<t>This uses the definitions in Sections <xref target="RFC8610" section="1" sectionFormat="bare">Introduction</xref>, <xref target="RFC8610" section="2" sectionFormat="bare">The Style of Data Structure Specification</xref>, and <xref target="RFC8610" section="3" sectionFormat="bare">Syntax</xref> and Appendices <xref target="RFC8610" section="B" sectionFormat="bare">ABNF</xref> and <xref target="RFC8610" section="G" sectionFormat="bare">Extended Diagnostic Notation</xref> of <xref target="RFC8610">CDDL</xref>.</t>

(**) https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/636

(***) https://github.com/cabo/kramdown-rfc2629/issues