Subject: [Rfc-markdown] using markdown for XML2RFC v3 I-Ds

From: Miek Gieben <[email-masked]>
Date: Tue, 2 Dec 2014 22:26:23 +0000

Hello,

I'm pondering a markdown syntax (mostly like CommonMark, but with a set of
extensions) for use when writing I-Ds for the XML2RFC v3 format. It steals
syntax from CommonMark, kramdown, leanpub and Asciidoc.

To play with it I've forked[1] blackfriday (a markdown converter written in
Golang), and implemented the following:

* TOML titleblock
* including other markdown files with the syntax: {{file}}
* indices with the syntax: (((Item, Subitem)))
* main-, middle- and backmatter document divisions, syntax: {mainmatter}, etc.
* citations, syntax: [@RFC223]
* reference section automatically created
* abstract, prefix paragraph with 'AB>'
* asides, prefix paragraph with 'A>'
* IAL, inline attribute lists from kramdown

It is a work-in-progress and the converter even still outputs some LaTeX blurbs.

A short example document can be found here:
https://raw.githubusercontent.com/miekg/blackfriday/master/ietf/ietf-markdown.md

Feedback welcome.

/Miek

[1]: https://github.com/miekg/blackfriday

--
Miek Gieben

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 3 Dec 2014 07:13:41 +0100

(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