Syntax

Elements of kramdown-rfc syntax

This page is a memo about the various elements of the kramdown-rfc syntax. It is not ordered by significance of the element, but by its technical aspects.

Additions to the kramdown syntax

Some additional syntax was added to the standard markdown syntax as already exhibited by kramdown. Reference: lib/kramdown-rfc2629.rb, i.e., class Kramdown::Parser::RFC2629Kramdown

{{}} syntax

In markdown, an internal reference with an empty link text should have the form [](#RFC7252). Interestingly, this syntax (empty link text) is specifically not supported by kramdown.

So the following syntax for an internal reference with empty link text was invented (note that the # is implied unless ref is a full URI [1.0.29]):

• {{ref}} for an internal reference, regardless of biblio, section, figure, table.
• {{?ref}} for a biblio reference that automatically generates the entry as informative
• {{!ref}} for a biblio reference that automatically generates the entry as normative

Where ref is not a valid XML ID, it is prefixed by an underscore.

To support referenced drafts evolving into RFCs without having to touch the entire document, they can be given a kramdown-internal symbolic name in the YAML, which is then referenced as {{-name}}. (1.0.29 adds support for adding alias names to other biblio references.)

((())) syntax

Markdown does not have syntax for index entries. kramdown-rfc emulates some asciidoc/pandoc syntax here.

• Leading ! ➔ primary flag is set
• item/optional subitem comma-separated, either one needs to be in quotes if it contains a comma

Mapping kramdown's markdown elements to RFCXML

It is not always straightforward how to elicit RFCXML behavior where markdown has been shaped by its HTML background.

Footnotes ➔ crefs

Math handling (mostly unimplemented)

Abbreviations ➔ automatic irefs

*[MUST]: BCP19
*[MAY]: BCP19
*[MUST NOT]: BCP19
*[SHALL]: BCP19

Special IAL attributes

(IAL = Inline Attribute List, a kramdown extension borrowed from Maruku. Note that the kramdown support for ALD = Attribute Definition Lists comes free of charge with markdown and has been used to factor out some ugly, repetitive IALs.)

Generally, IAL attributes are copied to the XML elements created. There is some special handling for

• id, which is usually translated to anchor, so the #id syntax can be used in IALs
• href, which is usually translated to target; in a link, it is translated to xref for internal links and eref for external ones; &foo; is converted to an entity reference

There are also some element-specific hacks, such as:

• translating artwork-align etc. on a figure to an align attribute etc. for the artwork in the figure.

• translating class for code blocks into type (after removing the language- inserted by kramdown)

• an attribute cols is translated into ttcol attributes for a table (so the writer does not have to memorize the arcane markdown table attribute syntax, which is also supported)

• element content is turned into title attributes where needed (with some markup loss)

• codespans are converted to style="verb", em/strong to emph/strong

• vspace hacks [TODO]

The YAML header

Mostly documented by examples in README.md