Skip to content

Syntax2

Jump to bottom Edit New page
Mark Nottingham edited this page Mar 2, 2024 · 53 revisions

This page is a work in progress.

This page documents syntax specific to kramdown-rfc2629. See kramdown's markdown syntax guide for generic syntax.

kramdown-rfc2629 documents are markdown documents with multiple sections, each delimited by a new line starting with --- and followed by a name. The possible sections are:

  • Structured Information - required
  • Abstract - required
  • Note(s) - optional
  • Main document - required
  • Appendices - optional

Structured Information

The very first YAML section has no name, and contains document metadata that maps to that expected by the XML format. This includes:

  • abbrev (string): Abbreviated variant of the document title
  • area (string): The IETF area to which this document relates
  • author (array of hashes): Information about a document's author(s); see below for content model
  • cat or category: Document category
  • date (date): Publication date
  • docname: The document filename
  • entity (hash): XML entity declarations that can be referenced as {{&entityname}} in the text.
  • informative (hash): Informative references; see below for content model
  • ipr (string): Intellectual property status of the document
  • kw (string): Keyword(s) applicable to the document
  • normative (hash): Normative references; see below for content model
  • number (string): The RFC number
  • obsoletes (string): RFC number(s) or Internet-Draft name(s) that this document will obsolete, comma-separated
  • pi (hash or array): Processing instructions to add to the XML. If a hash, names map to values; if an array, all values are "yes".
  • seriesno: (Deprecated. Translated to the seriesInfo value by the xml2rfc v2v3 converter.)
  • smart_quotes (array): Four entity names or character numbers to use as quotes (left single, right single, left double, right double).
  • title (string): The document title
  • updates (string): RFC number(s) or Internet-Draft name(s) that this document will update, comma-separated
  • v (integer): The version of xml2rfc syntax to produce; set this to 3 ordinarily, 2 only if you know what you are doing
  • venue (hash): Information about where the draft is discussed; see below for content model
  • wg or workgroup (string): The Working Group (IETF) or Research Group (IRTF) from which this document originates

For example:

---
title: My Amazing Document For Everyone To Read and Enjoy
abbrev: MyDoc
docname: draft-wizardsrus-amazing-doc-latest
date: 2021-10-05
category: info
ipr: trust200902
area: General
wg: gendispatch
keyword: fabulous
pi: [toc, tocindent, sort refs, symrefs, strict, compact, inline]
updates: 1000,1001
entity:
  SELF: "[RFCXXXX]"

Authors, Contributors

Authors (whether of the document of a reference) are hashes with the following content model:

  • abbrev: An abbreviation for the organization.
  • city: The author's city of residence.
  • code: The author's postal code.
  • country: The author's country of residence.
  • email: The author's e-mail address.
  • facsimile: The author's facsimile number.
  • ins: The author's abbreviated name -- initial(s), followed by surname. Only necessary for complex structures
  • name: The author's full name. Required
  • org: The author's organization.
  • phone: The author's telephone number.
  • region: The author's region of residence (e.g., state, province).
  • role: Set to editor if the author is an editor.
  • street: The author's street.
  • uri: A URI for the author (e.g., home page).

For example:

author:
  -
    name: John Doe
    ins: J. Doe
    country: Albania
    uri: https://example.com

In the YAML describing the document's authors, a similarly shaped contributors section can be added. To indicate the specific contribution of a contributor, the attribute contribution can be added.

author:
 - name: Carsten Bormann
   org: Universität Bremen TZI
   email: cabo@tzi.org
contributor:
 - name: Peter Occil
   email: poccil14 at gmail dot com
   contribution: |
     Peter Occil registered tags 30, 264, 265, 268–270
     ({{advanced-arithmetic}}), 38, 257, 266 and 267
     ({{domain-specific}}), and contributed much of the text about
     these tags in this document.
 - name: Jane Doe
   ...

Note how the YAML syntax of using a single vertical bar (|) followed by indented text content eases the addition of the markdown content in the contribution text.

References

The details of references used in the document are normally held in the normative and informative hashes, with each key of these hashes being used as the short reference identifier for the reference within the document.

The values of the references can take three forms: automatic, aliased, or full references, depending on your needs. Note that it is not necessary to list references in the structured information if they are fully-defined inline.

Automatic References

Automatic references occur when the reference identifier matches the form used in the xml2rfc citation libraries.

For example,

normative:
  RFC2119:
  I-D.ietf-core-block:
  W3C.REC-xml.xml:
  BCP190:
  STD0094:

Aliased References

An automatic reference can be aliased so that a different reference identifier is used in the document. For example,

informative:
  HTTP11: RFC7230

Here, both references to RFC7230 and the references section will use [HTTP11] as a reference identifier, instead of [RFC2730].

Full References

When a referenced document is not available in the xml2rfc citation libraries, the full reference format can be used. It is a hash with the following possible member:

  • - (string): An alias for the reference (see above)
  • ann (string): An annotation for the reference; shown after the generated reference text
  • author (array of hashes): The author(s) of the reference; see below for content model
  • date (date): The publication date of the reference
  • format (hash): The format(s) that the document is available in
  • refcontent or rc (string): Text that should appear between the title and the date of a reference (an RFCXMLv3 addition)
  • seriesinfo (hash): Intended for series information such as ISBN, DOI, RFC number. Sometimes abused in place of refcontent
  • target (string): A URL for the referenced document
  • title (string): The referenced document's title

For example,

informative:
  TypedArray:
    -: ta
    target: https://www.khronos.org/registry/typedarray/specs/1.0/
    title: Typed Array Specification
    author:
      -
        ins: V. Vukicevic
        name: Vladimir Vukicevic
        org: Mozilla Corporation
      -
        ins: K. Russell
        name: Kenneth Russell
        org: Google, Inc.
    seriesinfo:
      ISBN: 9780470747995
      DOI: 10.1109/MIC.2012.29
    date: 2011-02-08
    format:
      TXT: http://foo.bar/baz.txt
      PDF: http://foo.bar/baz.pdf
    ann: >
      This is a long annotation.

Venue

The contents of the venue hash are used to automatically generate a note section (see below) detailing where and how the draft can be discussed. It can contain the following members:

  • arch: A URL for the mailing list archive.
  • github: identifier for the relevant GitHub repository; e.g., "httpwg/http-extensions"
  • group: The name of the group responsible for the draft; e.g., "HTTP", "General Area Dispatch"
  • home: A URL for more information.
  • mail: The e-mail address for the draft's discussion list.
  • repo: A URL for the draft's repository.
  • type: The type of group; e.g., "Working Group", "Research Group". If not given, will be inferred from the e-mail address.

Flags

Flags instruct kramdown-rfc to vary the XML output:

  • autolink-iref-cleanup: when set to true, supresses auto-links (generated using the kramdown's "abbrev" syntax) from text inside a section when it links to the section itself; consolidate any index entries automatically generated to point to the entire section.

abstract -- Abstract

The abstract comes after the structured information, and is a short section describing the document's purpose.

For example,

--- abstract

This document documents how documents should document other documents.

Markup inside an abstract section has the same syntax as the main document.

note_* -- Note(s)

One or more additional sections can be created before or after the document content by staring a section header with note_ and appending what the section's title should become.

For example:

--- note_Note_to_Readers

You probably don't want to read this yet.

This will insert a section titled "Note to Readers" with the content indicated.

Markup inside a note section has the same syntax as document content.

middle -- Main Document

External References

References to external documents can take a few different forms.

Direct References

When a referenced document is defined under normative or informative in the structured information, it can be referenced inline using its reference identifier:

This is a very pleasing paragraph, but to fully understand it, 
you need to read the preceding specification {{RFC9999}}.

Inline References

Referenced documents in the xml2rfc citation libraries can be referenced inline, without including them in the structured information, by using the applicable reference identifier. At least one occurrence of inline references must indicate whether it is normative or informative by prefixing the reference identifier with ! or ?, respectively.

For example,

{{!RFC7230}} replaced {{?RFC2616}}, but {{?I-D.ietf-httpbis-semantics}} 
will eventually replace that.

Here, RFC7230 will be a normative reference, and RFC2616 and the semantics draft will be informative.

Inline references can contain section references (see below); e.g.

See {{!Section 1 of RFC7230}}.

Section References

A pinpoint into a section of the document can be referenced in several ways. In each case, while the keyword is Section, it will be transcribed as Appendix if the section number begins with a letter. Multiple sections can be referenced with the Sections keyword.

Section x.x of XXXX

{{Section 1.2.3 of RFC1234}}  # Section 1.2.3 of [RFC1234]
{{Section E.4 of RFC4567}}  # Appendix E.4 of [RFC4567]
{{Sections 1.2 and 3.4 of RFC1234}}  # Sections 1.2 and 3.4 of [RFC1234]
{{Sections 1 (Introduction), 2 (The Style of Data Structure Specification), and 3 (Syntax) and Appendices B (ABNF) and G (Extended Diagnostic Notation) of !RFC8610 (CDDL)}}.

XXXX, Section X.X

{{RFC1234, Section 1.2.3}}  # [RFC1234], Section 1.2.3
{{RFC4567, Section E.4}}  # [RFC4567], Appendix E.4
{{RFC1234, Sections 1.2 and 3.4}}  # [RFC1234], Sections 1.2 and 3.4

XXXX (Section X.X)

{{RFC1234 (Section 1.2.3)}}  # [RFC1234] (Section 1.2.3)
{{RFC4567 (Section E.4)}}  # [RFC1234] (Appendix E.4)
{{RFC1234 (Sections 1.2 and 3.4)  # [RFC1234] (Sections 1.2 and 3.4)

De-Aliased References

Sometimes, it may be desirable to use an alias only for authoring convenience; for example, when a reference is used in many places throughout the document but might change. In these cases, the reference can be preceded with - to indicate that the alias should not be used:

For example:

---
normative:
  RFC8610: cddl

--- middle
See {{-cddl}} for more information.

Here, the resulting reference will render as [RFC8610].

Internal References

References within a document can be made to anchors defined like this:

# The "widget" protocol element {#widget}

...

# The "foo" protocol element {#foo}

Foo is a widget ({{widget}}) that...

As a (somewhat brittle) simplification, kramdown automatically generates "slugified" (lower cased, separated with hyphens) anchors from the title:

# ...

Details about the new registries can be found in {{iana-considerations}}.

...

# IANA Considerations

(This is useful for shorter titles less like to change, such as IANA Considerations, Introduction, etc.)

Source Code and Artwork

Sourcecode and artwork elements are both generated with the code block syntax. For example:

~~~
Here is my example!
~~~

Just as in markdown, the language can be indicated:

~~~ xml
<thing></thing>
~~~

Many of these languages are used for actual sourcecode, such as programs, messages, data format examples.

The RFC editor has a set of preferred "sourcecode types" (languages for sourcecode).

You can use the language names ascii-art binary-art call-flow hex-dump and svg, as well as the absence of a language name, to trigger the generation of an artwork element; all other language names trigger the generation of a sourcecode element. (If this needs to be overridden, use gi in an IAL.)

Boilerplate

You can insert the standard RFC2119 boilerplate with this:

{::boilerplate bcp14-tagged}

Index Entries

A document index can be created by manually annotating each occurrence of the terms to be indexed, like this:

The (((!widget))) can be inserted into the (((flux capacitor))) when necessary.

Here, the occurrence of "widget" in this sentence will be flagged as the primary reference for the term in the index, due to the ! preceding the term. "Flux capacitor" will be indexed as well. Use quotes around terms with unusual characters.

Alternatively, indices can be automatically created by using the kramdown "abbrev" syntax somewhere in the document:

*[flux capacitor]:
*[widget]: Things

Here, all occurrences of "flux capacitor" in the document will be indexed, and all occurrences of "widget" will be indexed under "Things". You can cause these indexed terms to link to an anchor in the document as follows:

*[protocol]: #
*[protocol data unit]: #pdu

Here, all occurrences of "protocol" will be indexed and linked to the "protocol" anchor; all occurrences of "protocol data unit" will be indexed and linked to the "pdu" anchor.

Contact Names

The XML format only allows non-ASCII characters inside the <contact> element, and is accommodated in markdown using the {{{}}} syntax. For example,

{{{Jürgen Möllemann}}} and 
{{{トヨタ自動車株式会社}{Toyota Jidosha}}}

create contact elements with fullname and optionally asciiFullname attributes:

<contact fullname="Jürgen Möllemann"/> and 
<contact fullname="トヨタ自動車株式会社" asciiFullname="Toyota Jidosha"/></t>

(The transliteration of the second example is somewhat wrong, but we don’t have latinFullname, just asciiFullname; this will need to be fixed in the course of the upcoming beyond-ASCII renovation of RFCXMLv3.)

Note that with the current XML2RFC implementation of RFCXMLv3 there is no need to input asciiFullnames for fullnames that are using Latin characters only.

Comments

Editorial comments (crefs in the XML) can be created using the markdown syntax:

This is a questionable paragraph. [^1]{: source="joe"}

...

[^1]: So why not delete it?

If there are many comments with the same author, the syntax can be simplified with an Attribute List Definition:

{:joe: source="joe"}

This is a questionable paragraph. [^1]{:joe}

...

[^1]: So why not delete it?

Included Content

External file contents can be included; for example:

{::include ../traces/trace-1.out}

Note that inclusion will be disabled if the KRAMDOWN_SAFE environment variable is set.

Inline Attributes

Kramdown's Inline Attribute Lists are generally copied to the XML elements created for the content they're attached to. This allows fine control over the generated XML. For example,

~~~ yang
{::include yang/ietf-voucher-latest.yang}
~~~
{: sourcecode-markers="true" sourcecode-name="ietf-voucher@2021-07-02.yang”}

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; &xxx; 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 (same for sourcecode-markers and sourcecode-name).

  • 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

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

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

  • definition lists can be annotated one of three ways in one of four places:

    • The <dl> element is annotated by preceding the first definition with a block [IAL] that starts in the first column. This must be on the line immediately preceding that first definition (with no blank lines), which cannot contain any non-IAL content. See line 1 below.

    • Alternatively, the <dl> element can be annotated by following the last definition with a block [IAL], starting in the first column also.
      See line 9 below. Both top and bottom IALs are combined.

    • The <dt> element is annotated by preceding the definition line with an [IAL].
      See line 2 below.

    • The <dd> element can receive a block-level IAL by adding it to an indented line immediately after the definition text.
      See line 5 below.

1. {: newline="true"}
2. {:#dt-anchor} Definition:
3. 
4. : The body of the `<dd>` element contains a definition.
5.   {: anchor="definition-text"}   <!-- This is the long form of {:#definition-text}, as applied to the <dd> element -->
6.
7. Second Definition:
8. : The body of the second definition.
9. {:#dl-anchor}

back -- Appendices

Backwater contains the appendices of the document. For example,

--- back

# Acknowledgements
{: numbered="false"}

I'd like to thank the academy...

Markup inside a back section has the same syntax as the main document.

Add a custom footer
Add a custom sidebar
Clone this wiki locally