Re: [Rfc-markdown] [rfc-i] using markdown for XML2RFC v3 I-Ds

[Carsten Bormann <[e-mail]>]

(This is a bit off-topic for this list.
It seems to be about time to create one over at ietf.org…)

Obviously, I’m partial to the existing syntax here.
Lots of bikesheds.

> * TOML titleblock

kramdown-rfc2629 uses YAML, which is a superset of JSON.
This is a bit of a natural upgrade from multimarkdown’s ad-hoc syntax.

> * including other markdown files with the syntax: {{file}}

kramdown-rfc2629 uses {{xxx}} for xrefs (with some additional syntax for automatically creating literature references).
You can use kramdown’s {::include …} syntax for file includes.
(I think it is good to have some heavyweight, greppable syntax for that.)

> * indices with the syntax: (((Item, Subitem)))

This is one I intend to pick up from asciidoc, too.
Note that asciidoc/atlas has a lot more functionality here (e.g., ranges).
(I was thinking about also emulating RFC 7328’s ^[^item^ subitem] hack.
Not worth it if you are abandoning RFC 7328.)

> * main-, middle- and backmatter document divisions, syntax: {mainmatter}, etc.

I like kramdown-rfc2629’s section markers:

--- abstract
--- middle
--- back

(and
--- fluff
for parts that shouldn’t come out at all.)

> * citations, syntax: [@RFC223]

{{RFC20}} (with the automatics)
Or, if you want to mark text with it (no automatics, though:
[text to be marked](#RFC20)

> * reference section automatically created

Of course.
There needs to be a way to indicate what is normative and what is informative:
This can be done in the YAML header (where non-library references go, as well), or automatically by simply using {{?RFC4949}} (informative) and {{!RFC2119}} (normative).

> * abstract, prefix paragraph with 'AB>’

--- abstract

> * asides, prefix paragraph with 'A>’

Don’t have those yet.
(Right now I’m hijacking the PHP Markdown Extra footnote syntax for crefs, maybe I should unhijack that.)

> * IAL, inline attribute lists from kramdown

Indeed; these are probably the most useful contribution of maruku picked up by kramdown, including attribute list definitions to make these less onerous in the text.

Grüße, Carsten