Xml2RFC Documents
By Sylvain Fargier (EN-SMM-APC)
19 March 2019
Introduction
A tool to write technical documents:
- Focus on content not style
- Keep track of changes and versions
A publication tool:
- Style according to latest group guidelines
- Reference, index, search
Introduction: goals
Introduction: preview
Documents
A "stream" regroups a set of documents:
- Written by a working-group or a team (section, group, department ...)
- Defines statuses statements depending on the document's category and state, ex:
Documents: Streams
5 Categories: (STD, EXP, BCP, Info, Historic)
- A low variety to keep things simple and yet sufficient
- A color code to quickly identify the document
Documents: Categories
Standard Tracks
- A specification for which significant implementation and successful operational experience has been obtained.
Experimental
- a specification that is part of some research or development effort.
- Published for examination, experimental implementation and evaluation.
Document Categories: STD & EXP
Best Current Practices (BCP)
- A way to standardise practices, recommendations on what is believed to be the best way to perform some operations.
Informational (Info)
- Aggregates informational facts
- ! not a specification or recommendation document.
Document Categories: BCP & INFO
Historic
- A specification that has been superseded by a more recent specification or is for any other reason considered obsolete.
Document Categories: Historic
Pre-publication documents: Drafts
- 6 months lifespan until expiry
- can be promoted to regular document (using EDMS)
Pair-reviews: Consensus
- A simple state that indicates whereas the review status
- Additional information about reviewers in a dedicated section
Documents: Status
In document versioning and ChangeLog
- For document readers
- Additional information and context in a dedicated section
Using an SCM (git)
- for writers and in-depth investigation
Documents: Versions
Format and Syntax
The "xml2rfc" Version 3 Vocabulary [RFC7991]
- Widely used by RFC writers
- A limited set of tags (66), only a small subset frequently used (<10)
- Tools and validation schemas available
There will be examples ... and more
Format and Syntax
The "rfc" tag
- Main tag describing the document itself
Format and Syntax: tags
<rfc
category="std"
consensus="true"
docName="en-smm-apc-doc-guidelines-01"
submissionType="en-smm-apc" ...>Documents split in 3 parts:
- front : description, authoring, abstract ...
- middle : main content
- back : changelog, annexes, reviews ...
The "section" tag
- Split the document in sections and sub-sections
Format and Syntax: tags
<section>
<name>Historic</name>
<t>This is some text</t>
</section>
Yes, sounds awesome,
But ... I have an XML allergy ... and my doctor won't let me use it ...
A more user friendly syntax : PUG templating engine
- A lot less error prone than XML
- Keeps documents simple and human readable
Format and Syntax: PUG
section
name Historic
t This is some text<section>
<name>Historic</name>
<t>This is some text</t>
</section>
Quick PUG tour:
Format and Syntax: PUG
// This is a tag with an attribute
section(anchor='MY_ANCHOR')
// This is a tag with text content, inside our section
name Content examples
// This is another tag with text content inside our section
t This section will show a couple of RFC examples.
// This tag has several line of text
t
| Full syntax documentation can be found here:
| #[xref(target='RFC7991' format='default') RFC7991]
// The #[] is a short-hand for small tags (refs, quotes ...)There's more, but this really all what you need to know !
One last example for the skeptical :
Format and Syntax: PUG
section
name Content examples
t This section will show a couple of RFC examples.
t
| Full syntax documentation can be found here:
| #[xref(target='RFC7991' format='default') RFC7991]<section>
<name>Content examples</name>
<t>This section will show a couple of RFC examples.</t>
<t>Full syntax documentation can be found here:
<xref target="RFC7991" format="default">RFC7991</xref>
</t>
</section>Honestly, the logo is the best argument ever, look at that dog !
And what about diagrams, pictures, drawings
- Writers should use line-art : focus on content, not styling
- External documents may also be used
Format and Syntax: artwork
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Version| Prio. | Flow Label |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-++------+ +-----------+ +--------------+
| | UP | | OPENED | | SUCCESS/NONE
| Dead |------->| Establish |---------->| Authenticate |--+
| | | | | | |
+------+ +-----------+ +--------------+ |
^ | | |
| FAIL | FAIL | |
+<--------------+ +----------+ |
| | |
| +-----------+ | +---------+ |
| DOWN | | | CLOSING | | |
+------------| Terminate |<---+<----------| Network |<-+
| | | |
+-----------+ +---------+
Format and Syntax: artwork
figure
name Figure title
artwork(align="center" type="ascii-art")
| <![CDATA[
| +-------+ +---------------+
| | | | |
| | Jave5 <------> asciiflow.com |
| | | | |
| +-------+ +---------------+
| ]]>
figure
name External figure title
artwork(align="center" type="svg" src="template-long/pug.svg")Tools
Xml2RFC CERN version
- Supports xml and pug files
- Available as a docker image (gitlab-registry.cern.ch/apc/common/xml2rfc)
- See the README file for additional details
Tools: Xml2RFC
# Generate pdf/html/txt files
xml2rfc "example.pug"
# Watch for a file and generate documents on modification
xml2rfc-watch "example.pug"(pre)-Publication
Documents from the EN-SMM-APC stream:
- Are pre-published when pushed or merged on master branch of the docs gitlab
- pre-published documents are available on DFS (\\cern.ch\dfs\Websites\a\apc-dev\docs)
- Also browsable from apc-dev website
- And ...
(pre)-Publication: EN-SMM-APC stream
Indexed and pre-published on apc-dev website :
(pre)-Publication: EN-SMM-APC stream
Questions ?