[Rfc-markdown] 1.3.21: Section references (v3)

[Carsten Bormann <[e-mail]>]

1.3.21 supports clickable section references with RFCXMLv3,
i.e., if the --v3 (kdrfc -3) flag is given.

Since there is no existing markdown syntax for that, something had to invented.
In the spirit of markdown, this was supposed to be mostly natural keyboarding.
Of course, clickable section references always were possible using IALs, as in:

{{RFC3986}}{: section="3.1”}

Too much noise.  So why not just say:

{{Section 3.1 of RFC3986}}?

Which is exactly what happened.
RFCXMLv3 supports three styles (“of”, “comma”, and “parens”), and so does kramdown-rfc.

Reminder: this is the usual syntax for a whole-document reference:
* {{RFC8949}}

“of” syntax:
* {{Section 1 of RFC8949}} ➔ Section 1 of [RFC8949]
* {{Section E.5 of RFC8949}} ➔ Appendix E.5 of [RFC8949]

“comma” syntax:
* {{RFC8949, Section E.5}} ➔ [RFC8949], Appendix E.5

“parens” syntax:
* {{RFC8949 (Section E.5)}} ➔ [RFC8949] (Appendix E.5)

There also is a “bare” style, which is usually used only in multi-section references and therefore gets a bit more noisy syntax:

* {{E.5<RFC8949}} ➔ E.5 (which does point to E.5 of RFC 8949)

Kramdown-rfc also includes some basic support for multi-section references (based on the “bare” style above), with limitations:

* {{Sections 1 and E.5 of RFC8949}}
* {{Sections 1, 2, and E.5 of RFC8949}}
* {{RFC8949 (Sections 1 and E.5)}} ➔ Sections 1 and E.5 of [RFC8949]
* {{RFC8949, Sections 1, A, and E.5}} ➔ Sections 1, A, and E.5 of [RFC8949]

Limitations for now:

* Only recognizes “Section”/“Sections" in the reference syntax 
  (even when talking about Sections in the Appendix); could be fixed
* There is an inconsistency in xml2rfc’s appendix reference handling:
  https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/581
  This means that in practice appendix references do not work 
  until xml2rfc is fixed.
* Interactions with the !/? normative/informative signifiers 
  have not been implemented; TODO.

Limitations in multi-section references for now:

* Does not use “appendix” for references to sections in the appendix,
  or form proper English for mixtures of Sections and Appendices
  (But appendix references don’t work right now, anyway); this is a TODO
* Only can do "of” format for multi-section references 
  (recognizes the input syntaxes other forms, but shows them as "of" form); 
  for implementation reasons this may stay a WONTFIX
  (unless people really want that feature)

TLDR: Just write between the double braces what you think, and it is likely that kramdown-rfc can translate that into something useful.

(The fun thing is that this description is longer than the code that implements it :-)

Grüße, Carsten