Re: [Rfc-markdown] how to reference a draft, and a section within an RFC?

[Carsten Bormann <[e-mail]>]

Hi Paul,

On 25. Jan 2023, at 23:09, Paul Wouters <[e-mail]> wrote:
> 
> 
> I've inherited a draft in this markdown format.

Welcome to the club.

> It seems to try to reference a section using:
> 
> 	({{rfcxxxx}}, Section x.y)

The usual syntax is {{Section 3.11 of RFC8949}}

If you haven’t included the RFC in the YAML header, you can do this right inline with

{{Section 3.11 of ?RFC8949}} — informative
{{Section 3.11 of !RFC8949}} — normative

Or you can do this in the YAML header:

normative:
  RFC8949:

(No further data are needed, as they are fetched from the bibxml server bib.ietf.org.)

> but that seems to not work? And this says you cannot do it:
> 
> 	https://github.com/cabo/kramdown-rfc/issues/21

This is a very old issue, discussing the introduction of <relref seven years ago (an xml2rfc innovation that already is deprecated).

> Also, I can't find how to add a draft as reference. One would expect
> that {{draft-ietf-foobar}} would work, but it doesn’t.

The standard bibxml is using I-D.ietf-foobar as the standard anchor; so far we haven’t tried to change this.

If you like this anchor format, you can define your own alias anchors in the YAML header:

normative:
  draft-ietf-foobar: I-D.ietf-foobar

> I checked the examples/ dir and couldn't find examples either.
> 
> If there is documentation anywhere about the format, I would be
> happy to read it.

The readme at https://rfc.space has some detailed documentation.

A more introductory approach is taken by various wiki articles at this space.

Section references are specifically discussed at:

https://github.com/cabo/kramdown-rfc/wiki/Syntax2#section-references

More overview material at:

https://github.com/cabo/kramdown-rfc/wiki/Syntax#references

Also, this mailing list has some discussion of various kramdown features.
And of course, you can ask here (as you did!).

Enjoy!

Grüße, Carsten