Metanorma
On this page

Metanorma-IETF library documentation

Library documentation for Metanorma-IETF, the Metanorma flavor for IETF Internet-Drafts and RFCs. Synced from the upstream gem README at github.com/metanorma/metanorma-ietf.

metanorma-ietf lets you write IETF Internet-Drafts and RFCs via Metanorma.

Functionality

This gem processes Metanorma documents following a template for generating IETF deliverables.

Metanorma-IETF adheres to AsciiRFC syntax, an AsciiDoc syntax for writing IETF documents developed by the Metanorma team.

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 v3
    • Metanorma doctype: ietf
    • Metanorma file extension: xmlrfc (not xml!)

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 v3 format:

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.

For further information about the markup used, please refer to the Writing IETF I-Ds and RFCs using AsciiDoc & Metanorma.

Usage

The preferred way to invoke this gem is via the metanorma command:

$ metanorma --type ietf a.adoc                     # output RFC XML v3, text, HTML
metanorma --type ietf --extensions xmlrfc a.adoc # output RFC XML v3</code></pre></div><p>The gem translates the document into IETF XML RFC format. By default, the gem then runs the <code>xml2rfc</code> tool to generate text and HTML versions as well.</p></section><section id="_installation"><h2 id="_installation">Installation</h2><section id="_installation_metanorma"><h3 id="_installation_metanorma">Metanorma</h3><p>Please visit <a href="https://www.metanorma.com" target="_blank" rel="noopener">https://www.metanorma.com</a> for installation instructions for all platforms.</p></section><section id="_installation_gem_usage"><h3 id="_installation_gem_usage">Gem usage</h3><p>Add this line to your application&#39;s Gemfile:</p><div class="code-block" data-code-block><pre><code class="language-ruby">gem &quot;metanorma-ietf&quot;</code></pre></div><p>And then execute:</p><div class="code-block" data-code-block><pre><code class="language-console"> 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

See Writing IETF I-Ds and RFCs using AsciiDoc & Metanorma.

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

ifdef::env-github[] include::spec/examples/example-v3.adoc[] endif::[] ifndef::env-github[]

include::spec/examples/example-v3.adoc[]

endif::[]

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:

  1. Open an issue to discuss a new feature.
  2. Write tests to support your new feature.
  3. Make sure the entire test suite passes locally and on CI.
  4. Open a Pull Request.
  5. Squash your commits after receiving feedback.
  6. Party!

Credits

This gem is developed, maintained and funded by Ribose Inc.

Examples

Notes

Metanorma-IETF was formerly published as the asciidoctor-rfc gem.