metanorma-ietf
lets you write Internet-Drafts and RFCs in AsciiDoc, the
“asciidoctor-way”.
Formerly known as asciidoctor-rfc
.
Functionality
This gem processes Asciidoctor documents following a template for generating IETF International Standards.
This AsciiDoc syntax for writing IETF standards is called “AsciiRFC”.
The gem currently inherits from the https://github.com/metanorma/metanorma-standoc gem, and aligns closely to it.
The following outputs are generated:
-
RFC XML v2
-
Metanorma
doctype
:rfc2
-
Metanorma file extension:
xmlrfc
(notxml
!)
-
-
RFC XML v3
-
Metanorma
doctype
:rfc3
-
Metanorma file extension:
xmlrfc
(notxml
!)
-
The “xml2rfc” Vocabulary (hereinafter “RFC XML”) is an XML-based language used for writing Internet-Drafts and RFCs (RFC7322).
This gem allows you to author these types of documents in AsciiDoc, and outputs RFC XML output in both v3 and v2 formats:
Its syntax is designed to be “native-asciidoctor” as much as possible, with some templated use of attributes to convey added information for RFC XML output.
This README documents the AsciiRFC markup in full detail. For further information about AsciiRFC, please refer to the AsciiRFC IETF Internet-Draft.
Usage
The preferred way to invoke this gem is via the metanorma
command:
$ metanorma --type rfc3 a.adoc # output RFC XML v3
$ metanorma --type rfc3 --extensions xmlrfc a.adoc # output RFC XML v3
The gem translates the document into IETF XML RFC format.
Text and HTML versions should be generated using the xml2rfc
tool.
Installation
Metanorma
Please visit https://www.metanorma.com for installation instructions for all platforms.
Gem usage
Add this line to your application’s Gemfile:
gem "metanorma-ietf"
And then execute:
$ bundle
Quick Start / Template
Clone the
rfc-asciirfc-minimal
repository as a template, and populate it for your Asciidoc RFCs and
Internet-Drafts:
$ git clone https://github.com/metanorma/rfc-asciirfc-minimal
See the README of that document for more information.
Documentation
Usage
Converting your AsciiDoc to RFC XML is a simple as running the appropriate
metanorma
command.
Once processing completes, you should see the RFC XML file draft-example-00.xml
in the
same directory.
RFC XML v3 Example
link:spec/examples/example-v3.adoc[role=include]
RFC XML v2 Example
link:spec/examples/example-v2.adoc[role=include]
Development
We follow Sandi Metz’s Rules for this gem, you can read the description of the rules here.
All new code should follow these rules. If you make changes in a pre-existing file that violates these rules you should fix the violations as part of your contribution.
Setup
Clone the repository.
git clone https://github.com/metanorma/metanorma-ietf
Setup your environment.
bin/setup
Run the test suite
bin/rspec
Contributing
First, thank you for contributing! We love pull requests from everyone. By participating in this project, you hereby grant Ribose Inc. the right to grant or transfer an unlimited number of non exclusive licenses or sub-licenses to third parties, under the copyright covering the contribution to use the contribution by all means.
Here are a few technical guidelines to follow:
-
Open an issue to discuss a new feature.
-
Write tests to support your new feature.
-
Make sure the entire test suite passes locally and on CI.
-
Open a Pull Request.
-
Squash your commits after receiving feedback.
-
Party!
Credits
This gem is developed, maintained and funded by Ribose Inc.