"oxtradoc" performs the translation from plain text into xml2rfc-style XML content. Specific rules must be followed, but the text input is generally readable and simple to understand.
Section Contents:
Emacs has a mode called "outline mode", which allows organization of text. "outline mode" has numerous functions for displaying and traversing these hierachies. See https://www.emacswiki.org/emacs/OutlineMode for details.
Another mode called "org mode" extends this mode with additional formatting conventions. "org mode" is a super set of "outline mode" and can be used similarly. See http://orgmode.org for details.
- Headings are in Emacs "outline mode", where heading depth is indicated a leading series of asterisks ("*"). The more asteriskss, the deeper the heading.
* History
** Early History
*** History That Time Forgot
** Middle History
** Late History
*** Missing History
**** Dog Ate My History
- References can be make to URLs, anchors (headings), or external references. A reference uses the convention of the target surrounded by up-hats:
The source of the Nile (^NILESOURCE^) was
unknown (^NILEHISTORY^).
- Headings can be used as the anchors. An explicit anchor name can be provided by placing the name at the end of the heading line between "at" signs ("@"), e.g. "@anchor‑name@".
*** Possible Sources of the Nile @NILESOURCE@
- If no explicit name is given, the anchor name will be the heading content with the following conversions:
- Upper case is translation into lower case.
- Spaces are translated into dashes ("‑").
- Any non-alphanumeric characters besides dash and underscore are removed.
- A reference to an internal anchor is translated to the section number of the anchor's heading, prefixed with the word "Section", e.g. "Section 4.2.1". To suppress the prefix, use dual uphats:
See sections ^^ref-one^^ and ^^ref-two^^.
- Paragraphs of text are separated by blank links, just like one types normally.
We are met on a great battlefield of that war. We have come to
dedicate a portion of that field as a final resting place for
those who here gave their lives that that nation might live.
It is altogether fitting and proper that we should do this. But
in a larger sense we can not dedicate -- we can not consecrate --
we can not hallow -- this ground. The brave men living and dead
who struggled here have consecrated it far above our poor power to
add or detract.
The world will little note nor long remember what we say here but
it can never forget what they did here. It is for us the living
rather to be dedicated here to the unfinished work which they who
fought here have thus far so nobly advanced
Figures, XML, code, and ASCII art can be placed directly in the file by indenting the content. When text is intended, the other rules of formatting are not applied. While "oxtradoc" can detect the "type" of the content (in terms of XML, code, artwork, etc), any such content is wrapped in the xml2rfc "figure" and "artwork" tags, and is not formatted.
Example:
+----+ +------+ +-------------+
| me |-->(emacs)-->| text |-->(oxtradoc)-->|documentation|
+----+ +------+ +-------------+
Example:
<rpc>
<order-lunch>
<togo/>
<pizza>
<size><large/></size>
<topping><sausage/></topping>
</pizza>
</order-lunch>
</rpc>
Note that there is no need to hand-escape less-than and greater-than characters; "oxtradoc" does this automatically.
Section Contents:
Figures can be placed in external files and included using the filename using a line containing "!!include‑figure":
!!include-figure ex-content.xml
An "extract‑to" value can be added to indicate a desired extraction filename:
!!include-figure my.yang extract-to="my-@2017-04-01.yang"
Putting such content in external files allows the content to be validated, as well as allowing text editors to apply mode-specific behaviors such as intentation or colored display.
"oxtradoc" supports a number of types of lists, based on simple text encoding conventions.
Section Contents:
A dash ("‑") at the beginning of the line marks a symbol list item, where the item will be prefixed with a symbol.
Example::
Favorite Things:
- Raindrops on roses
- Whiskers on kittens
Formatted output::
Favorite Things:
- Raindrops on roses
- Whiskers on kittens
An underscore ("_") at the beginning of the line marks an empty list item, where the item will not be prefixed with a symbol. This allows the lines to be adjacent without being wrapped together.
Example::
_ Do not pass Go
_ Do not collect $200
Formatted output::
- Do not pass Go
- Do not collect $200
A plus sign ("+") at the beginning of the line marks a numbered list item, where the item is prefixed with an increasing integer number.
Example::
+ The money
+ The show
+ Get ready
+ Go, Cat, Go!
Formatted output::
- The money
- The show
- Get ready
- Go, Cat, Go!
An equals sign ("=") at the beginning of the line marks an hanging list item, where the rest of the line is the hang text and the following lines are the content.
Example::
= 64-bit
Machines that have 64-bit CPUs
= 32-bit
Machines that have 32-bit CPUs
= 8-bit
Machines that are really, really old
Formatted output::
- 64-bit
- Machines that have 64-bit CPUs
- 32-bit
- Machines that have 32-bit CPUs
- 8-bit
- Machines that are really, really old
oxtradoc using "org mode" tables. These tables are simple, visually accurate, and can be automatically generated using Emacs tools. See http://orgmode.org/guide/Tables.html for additional information.
The rules for these tables are fairly simple:
- Tables start with a vertical bar ("|").
- Table headers appear next, separated by vertical bars.
- A separator line follows, containing vertical bars and plus signs.
- Content follows, separated by vertical bars.
- If a title is needed, the table is preceeded by a line containing two dashes, the title, and an optional anchor:
Example::
-- List of Sub-Statements @sub-list@
| substatement | section | cardinality |
|--------------+-----------------+-------------|
| argument | ^extension-arg^ | 0..1 |
| description | ^description^ | 0..1 |
| reference | ^reference^ | 0..1 |
| status | ^status^ | 0..1 |
Formatted output::
Table 1: List of Sub-Statements
Digressions are sub-blocks of texts that don't appear in the RFC. There are three types of digressions: document blocks, references blocks, and open questions.
A digress begins with a line that starts with two open braces ("{{") followed by the name of the block and a colon (":"). The digress ends with a line containing two close braces ("}}").
{{type-name:
contents
of the
digress
}}
Digressions of unknown type are ignored completely.
Section Contents:
| Open Question |
|---|
| Note that this needs to be updated for RFC7991, which deprecates some of these fields. |
The "document" digression contains information about the document and is used for RFC header fields. The contents of the digression are name/value pairs on lines ending with semi-colons:
{{document:
ipr pre5378Trust200902;
category std;
references back.xml;
abbreviation YANG;
title "The YANG 12.0 Data Modeling Language";
contributor "author:Joe Example:Example Inc:j@example.com";
keyword NETCONF;
keyword XML;
keyword "data modeling";
}}
Document values are taken from both the document section and the arguments to oxtradoc, with the latter taking precedence. The following section lists the name, options, and contents of the variables fields within the document digression:
- name (-n)
- Name of the document, suitable for rfc/@docName.
- ipr (-i) (default "none")
- IPR classification, suitable for rfc/@ipr.
- category (-c)
- Category of the document, suitable for rfc/@category.
- references
- Lists a file containing the references, in XML format. See Section 2.1.6.3 for additional information.
- abbreviation (-a)
- Short name of the document, suitable for rfc/front/title/@abbrev.
- title (-t)
- Formal title of the document, suitable for rfc/front/title.
- contributor
- Lists information about a document contributor, and may appear multiple times. Each value should be a role, name, organization, and email address separated by colons.
- keyword
- Keywords for the document, suitable for rfc/front/keyword. This line may appear multiple times to supply a set of keywords.
A "open question" digress is used to record an open question within the document for the benefit of the document authors. The question should be resolved before publication. An open question can be entered using a "question" digression, or may appear in a line that starts with a question mark.
? Are we sure we want to encode this in EBCDIC?
External references are handled by oxtradoc using a two-phase approach. Typically a "refences.txt" file is created by the document author that lists the references used in the document. The digression can appear directly in the document, but there is some significant processing involved in turning this simple list into the complex and verbose XML that xml2rfc needs for references. "oxtradoc -m mkback" turns a references file ("references.txt") into a suitable XML file ("references.xml"). The Makefile for rfcdoc handles this dependency automatically.
The format of the references file is a digression with the name "references". The digression contains a "title" and a series of reference names. The title for a references digression can be "Normative References" or "Informative References":
{{references:
title "Informative References";
ietf-ref RFC2119;
ietf-ref RFC6241;
ietf-ref I-D.ietf-netmod-revised-datastores;
}}
- Lines starting with pound signs ("#") are comments and are ignored.
- Lines starting with at signs ("@") are passed through upchanged. This serves as an escape mechanism for avoiding oxtradoc processing or for allowing pre-formatted content. Consider it as an option of last resort.
Since github.com supports "org mode" rendering of ".org" files, naming your file with a ".org" extension means automatic rendering of a subset of oxtradoc features in the github file display.