Subject: [Rfc-markdown] Markdown syntax for rfcs

From: Miek Gieben <[email-masked]>
Date: Fri, 5 Dec 2014 11:52:58 +0000

[ This was sent to rfc-interest, but now that we have our own list, I'm
   resending it here]

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, pandoc, 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}} (and maybe
     <<{{file}}} for including code (also from leanpub syntax)
* indices with the syntax: (((Item, Subitem)))
* main-, middle- and backmatter document divisions, syntax: {mainmatter}, etc.
* citations, syntax: [@RFC223], allows to specify normative/informative and
     reference file
* reference section automatically created
* abstract, prefix paragraph with 'AB>'
* asides, prefix paragraph with 'A>'
* figures, prefix parageaph with 'F>'
* IAL, inline attribute lists from kramdown

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

I am also pondering a name change from blackfriday to something else, possibly
mmark, to make it clear it isn't blackfriday anymore.

I'm keeping an eye out for RFC 7328 for keeping this syntax backward compatible.

*And* and will create a short document along the lines of draft-hoffman-xml2rfc
that will show the markdown constructs to use.

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: Sat, 6 Dec 2014 08:32:44 +0100

> https://raw.githubusercontent.com/miekg/blackfriday/master/ietf/ietf-markdown.md

I have done something roughly equivalent, using the stable kramdown syntax, at:

http://tzi.de/~cabo/ietf-markdown.mkd
http://tzi.de/~cabo/ietf-markdown.xml  (generated by kramdown-rfc2629*)
http://tzi.de/~cabo/ietf-markdown.txt  (generated by XML2RFC from that)

Incidentally, I have also pushed version 1.0.22 (support for index entries, roughly in asciidoc syntax), and a documentation update (as always, at: https://github.com/cabo/kramdown-rfc2629 — Internet Draft will follow in my copious spare time).

Grüße, Carsten

*) Note that this is not the stand_alone version, so you will see some error messages in a browser and the references do not show up.