Support other `sectionFormat` options for xrefs

[aarongable]

What went wrong?

I attempted to reference another RFC, with the desired output being text of the form "See [RFC1234], Section 1.2."

To achieve this goal, I wrote See [@RFC1234, section 1.2]., as suggested by the docs. However, this resulted in text of the form "See 1.2".

In order to get the result I wanted, I had to type the very verbose/redundant See [@RFC1234], Section [@RFC1234, section 1.2].

This is because mmark produces xrefs with sectionFormat=bare. There are many other sectionFormats that have useful behavior. It would be good to be able to specify that we want the "of", "comma", or "parens" behavior.

What version of mmark are you using?

2.2.16

What is the most minimal markdown snippets that shows the problem?

See [@RFC1234, section 1.2]

[miekg]

What syntax would you propose? Preferably something that looks natural. Maybe kramdown's markdown variant has some ideas here?

This is nice

Since version 1.1, references imported from the XML2RFC databases can be supplied with a replacement label (anchor name). E.g., RFC 793 could be referenced as {{!TCP=RFC0793}}, further references then just can say {{TCP}}; both will get [TCP] as the label. In the YAML, the same replacement can be expressed as in the first example:

[miekg]

also note that this piece of the reference structure is 'half fleshed out' precisely because of these new attributes that keep appearing.

[miekg]

Maybe we can use the syntax from xml2rfc directly here:

sectionFormat="of":
    See Section 1.3 of [RFC7991].
sectionFormat="comma":
    See [RFC7991], Section 1.3.
sectionFormat="parens":
    See [RFC7991] (Section 1.3).
sectionFormat="bare":
    See 1.3.

[aarongable]

Obviously, ideally, mmark would be able to parse all three of:

[Section 1.3 of @RFC1234] --> sectionFormat="of"
[@RFC1234, Section 1.3]   --> sectionFormat="comma"
[@RFC1234 (Section 1.3]   --> sectionFormat="parens"

But equally obviously, that's a pain for parsing, and additional formats that are harder to parse might show up in the future.

Personally, I'd introduce a semicolon syntax:

[@RFC1234; 1.3; format="of"]     --> Section 1.3 of [RFC1234]
[@RFC1234; 1.3; format="comma"]  --> [RFC1234], Section 1.3
[@RFC1234; 1.3; format="parens"] --> [RFC1234] (Section 1.3)
[@RFC1234; 1.3; format="bare"]   --> 1.3

Additionally, if you're not worried about backwards compatibility (not sure what guarantees you make), I'd change the current syntax to default to sectionFormat="of", rather than sectionFormat="bare", to share the same default as xml2rfc itself.

[miekg]

Thanks,

Personally, I'd introduce a semicolon syntax:

@.; 1.3; format="of"] --> Section 1.3 of [RFC1234] @.; 1.3; format="comma"] --> [RFC1234], Section 1.3 @.; 1.3; format="parens"] --> [RFC1234] (Section 1.3) @.; 1.3; format="bare"] --> 1.3

this works, but the problem I have is that it mimics block-level-attributes, but really isn't.

Let me ponder this a bit more, and look again at pandoc.

[miekg]

Ok, wrote this in Syntax.md (no code changes yet)

#### Reference Text Suffices

You can specify extra text after the citation using a comma: `[@RFC2535, section 5]`, see
<https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html#name-how-do-i-link-to-multiple-se>.
This is used in the following manner:

* `[@RFC2535, section 5]` -> sectionFormat="of"
* `[@RFC2525, see, section 5]` -> sectionFormat="comma"
* `[@RFC2525, (see) section 5]` -> sectionFormat="parens"
* `[@RFC2525, 5]` -> sectionFormat="bare"

Somewhat more inline with what we have now and (personally) I think this reads better in the bare markdown

[miekg]

tentative pr: https://github.com/mmarkdown/mmark/pull/152

[miekg]

closed via #152