Markdown for XML2RFC v3

November 27, 2014

docs

Or… how to write Markdown to generate XML that is valid XML2RFC v3. These are some assorted notes and ideas

Goal:

  1. Self contained file with all information to generate a complete I-D;
  2. CommonMarkdown, with some extension.

I’m working on implementing these ideas in blackfriday. The following has already been implemented:

  • Abstract;
  • Citation;
  • Document divisions;
  • Index;
  • File inclusion;
  • Extra attributes (kramdown’s IAL.) (work-in-progress).

Document meta data

In TOML - much easier than YAML for instance, lines are starting with %. We don’t need to specify the citations here because:

Citations

Use the reference syntax: [p. 23][#RFC2535], which can be extended to include a filename where the reference is:

[p. 23][#RFC2335,bib/reference.RFC.2525.xml]

They can optionally have ‘n’ or ‘i’ modifier to normative or informative reference. The reference section is automatically generated. Here is a normative and informative reference:

[][n#RFC2335,bib/reference.RFC.2525.xml]
[][i#RFC2335,bib/reference.RFC.2525.xml]

The default is informative. This only have to be done once, after that you can just use [][#RFC2535].

Abstract, notes and asides

Abstract is done with prefixing a paragraph with AB>, notes: N> and aside with A>.

Extra Attributes

CommonMark (seems?) to have adapted the kramdown IAL syntax but dropped the colon, so we would use {.class key=value} to add attributes to block elements.

Document Divisions

The front-, middle- and back-sections are signalled with:

{frontmatter}, {middlematter} and {backmatter}, where a document automatically starts with a frontmatter.

Index

Using triple parentheses, like so: (((Cats, Tiger))).

Including Markdown files

Use the syntax {{file}} will get file included.

All of the above use the extension syntax, i.e. starting with a { .

Quotes attribution?

> this is an quote
-- Miek Gieben

BCP14 keywords?

Uppercase in asterisks *MUST*.

XML  CommonMark  Markdown  XML2RFC  Mmark