-
Notifications
You must be signed in to change notification settings - Fork 82
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.
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
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.)
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
It is not always straightforward how to elicit RFCXML behavior where markdown has been shaped by its HTML background.
*[MUST]: BCP19
*[MAY]: BCP19
*[MUST NOT]: BCP19
*[SHALL]: BCP19
(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 toanchor
, so the#id
syntax can be used in IALs -
href
, which is usually translated totarget
; in a link, it is translated toxref
for internal links anderef
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 analign
attribute etc. for the artwork in the figure. -
translating
class
for code blocks intotype
(after removing thelanguage-
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 toemph
/strong
-
vspace
hacks [TODO]
Mostly documented by examples in README.md