[rfc-i] using markdown for XML2RFC v3 I-Ds
cabo at tzi.org (Carsten Bormann) Wed, 03 December 2014 06:13 UTC
From: "cabo at tzi.org"
Date: Wed, 03 Dec 2014 07:13:41 +0100
Subject: [rfc-i] using markdown for XML2RFC v3 I-Ds
In-Reply-To: <20141202222623.GA15228@miek.nl>
References: <20141202222623.GA15228@miek.nl>
Message-ID: <4AFB2C96-1BFF-4124-8E4A-2FCB8E21B2AB@tzi.org>
(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
- [rfc-i] using markdown for XML2RFC v3 I-Ds Miek Gieben
- [rfc-i] using markdown for XML2RFC v3 I-Ds Carsten Bormann
- [rfc-i] using markdown for XML2RFC v3 I-Ds Miek Gieben
- [rfc-i] using markdown for XML2RFC v3 I-Ds Sarah Banks