= AsciiRFC: Writing Internet-Drafts and RFCs in AsciiDoc :source-highlighter: coderay :icons: font `metanorma-ietf` lets you write IETF Internet-Drafts and RFCs via Metanorma. image:https://img.shields.io/gem/v/metanorma-ietf.svg["Gem Version", link="https://rubygems.org/gems/metanorma-ietf"] image:https://github.com/metanorma/metanorma-ietf/workflows/rake/badge.svg["Build Status", link="https://github.com/metanorma/metanorma-ietf/actions?workflow=rake"] image:https://codeclimate.com/github/metanorma/metanorma-ietf/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/metanorma-ietf"] image:https://img.shields.io/github/issues-pr-raw/metanorma/metanorma-ietf.svg["Pull Requests", link="https://github.com/metanorma/metanorma-ietf/pulls"] image:https://img.shields.io/github/commits-since/metanorma/metanorma-ietf/latest.svg["Commits since latest",link="https://github.com/metanorma/metanorma-ietf/releases"] == Functionality This gem processes https://www.metanorma.com[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 v2 ** Metanorma `doctype`: `rfc2` ** Metanorma file extension: `xmlrfc` (not `xml`!) * RFC XML v3 ** Metanorma `doctype`: `rfc3` ** Metanorma file extension: `xmlrfc` (not `xml`!) The "`xml2rfc`" Vocabulary (hereinafter "`RFC XML`") is an XML-based language used for writing https://www.ietf.org/id-info/guidelines.html[Internet-Drafts] and https://tools.ietf.org/html/rfc7322[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: * v3 RFC XML (https://tools.ietf.org/html/rfc7991[RFC 7991]) * v2 RFC XML (https://tools.ietf.org/html/rfc7749[RFC 7749]) 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 https://datatracker.ietf.org/doc/draft-ribose-asciirfc/[AsciiRFC IETF Internet-Draft]. == Usage The preferred way to invoke this gem is via the `metanorma` command: [source,console] ---- $ 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: [source,ruby] ---- gem "metanorma-ietf" ---- And then execute: [source,console] ---- $ bundle ---- == Quick Start / Template Clone the https://github.com/metanorma/rfc-asciirfc-minimal[`rfc-asciirfc-minimal`] repository as a template, and populate it for your Asciidoc RFCs and Internet-Drafts: [source,console] ---- $ git clone https://github.com/metanorma/rfc-asciirfc-minimal ---- See the https://github.com/metanorma/rfc-asciirfc-minimal[README] of that document for more information. == Documentation See https://www.metanorma.com/author/ietf/[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[] [source,asciidoc] ---- include::spec/examples/example-v3.adoc[] ---- endif::[] === RFC XML v2 Example ifdef::env-github[] include::spec/examples/example-v2.adoc[] endif::[] ifndef::env-github[] [source,asciidoc] ---- include::spec/examples/example-v2.adoc[] ---- endif::[] == Development We follow Sandi Metz's Rules for this gem, you can read the http://robots.thoughtbot.com/post/50655960596/sandi-metz-rules-for-developers[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. [source,sh] ---- git clone https://github.com/metanorma/metanorma-ietf ---- Setup your environment. [source,sh] ---- bin/setup ---- Run the test suite [source,sh] ---- bin/rspec ---- == Contributing First, thank you for contributing! We love pull requests from everyone. By participating in this project, you hereby grant https://www.ribose.com[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 https://github.com/metanorma/metanorma-ietf/issues[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. . https://github.com/thoughtbot/guides/tree/master/protocol/git#write-a-feature[Squash your commits] after receiving feedback. . Party! == Credits This gem is developed, maintained and funded by https://www.ribose.com[Ribose Inc.] == Examples //// * Example documents are avalable at the https://github.com/metanorma/mn-samples-ietf[mn-samples-ietf] repository. //// * Document templates are available at the https://github.com/metanorma/mn-templates-ietf[mn-templates-ietf] repository. == Notes Metanorma-IETF was formerly published as the `asciidoctor-rfc` gem.