asciidoctor-rfc 0.1.0 → 0.2.0

data/spec/asciidoctor/rfc/v3/sidebar_spec.rb

@@ -0,0 +1,30 @@
+require "spec_helper"
+describe Asciidoctor::RFC::V3::Converter do
+  it "renders a sidebar" do
+    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3)).to be_equivalent_to <<~'OUTPUT'
+      [[id]]
+      ****
+      Sidebar
+
+      Another sidebar
+
+      * This is a list
+
+      ....
+      And this is ascii-art
+      ....
+      ****
+    INPUT
+      <aside anchor="id">
+      <t>Sidebar</t>
+      <t>Another sidebar</t>
+      <ul>
+      <li>This is a list</li>
+      </ul>
+      <figure>
+      <artwork type="ascii-art">And this is ascii-art</artwork>
+      </figure>
+      </aside>
+    OUTPUT
+  end
+end

data/spec/asciidoctor/rfc/v3/table_spec.rb

@@ -0,0 +1,275 @@
+require "spec_helper"
+describe Asciidoctor::RFC::V3::Converter do
+  it "renders a table" do
+    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3)).to be_equivalent_to <<~'OUTPUT'
+      = Document title
+      Author
+
+      == Section 1
+      [[id]]
+      .Table Title
+      |===
+      |[[id]] head | head
+
+      h|header cell | body cell
+      | | body cell
+      2+| colspan of 2
+      .2+|rowspan of 2 | cell
+      |cell
+      ^|centre aligned cell | cell
+      <|left aligned cell | cell
+      >|right aligned cell | cell
+      |foot | foot
+      |===
+    INPUT
+      <section anchor="_section_1" numbered="false">
+      <name>Section 1</name>
+      <table anchor="id">
+      <name>Table Title</name>
+      <thead>
+      <tr>
+      <th align="left"> head</th>
+      <th align="left">head</th>
+      </tr>
+      </thead>
+      <tbody>
+      <tr>
+      <th align="left">header cell</th>
+      <td align="left">body cell</td>
+      </tr>
+      <tr>
+      <td align="left"></td>
+      <td align="left">body cell</td>
+      </tr>
+      <tr>
+      <td colspan="2" align="left">colspan of 2</td>
+      </tr>
+      <tr>
+      <td rowspan="2" align="left">rowspan of 2</td>
+      <td align="left">cell</td>
+      </tr>
+      <tr>
+      <td align="left">cell</td>
+      </tr>
+      <tr>
+      <td align="center">centre aligned cell</td>
+      <td align="left">cell</td>
+      </tr>
+      <tr>
+      <td align="left">left aligned cell</td>
+      <td align="left">cell</td>
+      </tr>
+      <tr>
+      <td align="right">right aligned cell</td>
+      <td align="left">cell</td>
+      </tr>
+      <tr>
+      <td align="left">foot</td>
+      <td align="left">foot</td>
+      </tr>
+      </tbody>
+      </table>
+      </section>
+    OUTPUT
+  end
+  it "ignores cell anchors in a table" do
+    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3)).to be_equivalent_to <<~'OUTPUT'
+      = Document title
+      Author
+
+      == Section 1
+      [[id]]
+      .Table Title
+      |===
+      |[[id]] head | head
+
+      h|header cell | body cell
+      | | [[id]] body cell
+      2+| colspan of 2
+      .2+|rowspan of 2 | cell
+      |cell
+      ^|centre aligned cell | cell
+      <|left aligned cell | cell
+      >|right aligned cell | cell
+      |foot | foot
+      |===
+    INPUT
+      <section anchor="_section_1" numbered="false">
+      <name>Section 1</name>
+      <table anchor="id">
+      <name>Table Title</name>
+      <thead>
+      <tr>
+      <th align="left"> head</th>
+      <th align="left">head</th>
+      </tr>
+      </thead>
+      <tbody>
+      <tr>
+      <th align="left">header cell</th>
+      <td align="left">body cell</td>
+      </tr>
+      <tr>
+      <td align="left"></td>
+      <td align="left"> body cell</td>
+      </tr>
+      <tr>
+      <td colspan="2" align="left">colspan of 2</td>
+      </tr>
+      <tr>
+      <td rowspan="2" align="left">rowspan of 2</td>
+      <td align="left">cell</td>
+      </tr>
+      <tr>
+      <td align="left">cell</td>
+      </tr>
+      <tr>
+      <td align="center">centre aligned cell</td>
+      <td align="left">cell</td>
+      </tr>
+      <tr>
+      <td align="left">left aligned cell</td>
+      <td align="left">cell</td>
+      </tr>
+      <tr>
+      <td align="right">right aligned cell</td>
+      <td align="left">cell</td>
+      </tr>
+      <tr>
+      <td align="left">foot</td>
+      <td align="left">foot</td>
+      </tr>
+      </tbody>
+      </table>
+      </section>
+    OUTPUT
+  end
+  it "renders inline formatting within a table" do
+    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3)).to be_equivalent_to <<~'OUTPUT'
+      = Document title
+      Author
+
+      == Section 1
+      .Table Title
+      |===
+      |head | head
+
+      h|header cell | *body* _cell_
+      | | body cell<<x>>
+      ^|centre aligned cell | cell
+      <|left aligned cell | cell
+      >|right aligned cell | cell
+
+      |foot | foot
+      |===
+    INPUT
+      <section anchor="_section_1" numbered="false">
+      <name>Section 1</name>
+      <table>
+         <name>Table Title</name>
+         <thead>
+           <tr>
+             <th align="left">head</th>
+             <th align="left">head</th>
+           </tr>
+         </thead>
+         <tbody>
+           <tr>
+             <th align="left">header cell</th>
+             <td align="left"><strong>body</strong> <em>cell</em></td>
+           </tr>
+           <tr>
+             <td align="left"/>
+             <td align="left">body cell<xref target="x"/></td>
+           </tr>
+           <tr>
+             <td align="center">centre aligned cell</td>
+             <td align="left">cell</td>
+           </tr>
+           <tr>
+             <td align="left">left aligned cell</td>
+             <td align="left">cell</td>
+           </tr>
+           <tr>
+             <td align="right">right aligned cell</td>
+             <td align="left">cell</td>
+           </tr>
+           <tr>
+             <td align="left">foot</td>
+             <td align="left">foot</td>
+           </tr>
+         </tbody>
+      </table>
+      </section>
+    OUTPUT
+  end
+  it "renders block formatting within a table" do
+    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3)).to be_equivalent_to <<~'OUTPUT'
+      = Document title
+      :docName:
+      Author
+
+      == Section 1
+      [cols="2"]
+      .Table Title
+      |===
+      |head | head
+
+      h|header cell
+      a|
+      * List 1
+      * List 2
+      | | body cell<<x>>
+      ^|centre aligned cell | cell
+      <|left aligned cell | cell
+      >|right aligned cell | cell
+
+      |foot | foot
+      |===
+    INPUT
+      <section anchor="_section_1" numbered="false">
+      <name>Section 1</name>
+      <table>
+         <name>Table Title</name>
+         <thead>
+           <tr>
+             <th align="left">head</th>
+             <th align="left">head</th>
+           </tr>
+         </thead>
+         <tbody>
+           <tr>
+             <th align="left">header cell</th>
+             <td align="left">
+               <ul>
+         <li>List 1</li>
+         <li>List 2</li>
+       </ul>
+             </td>
+           </tr>
+           <tr>
+             <td align="left"/>
+             <td align="left">body cell<xref target="x"/></td>
+           </tr>
+           <tr>
+             <td align="center">centre aligned cell</td>
+             <td align="left">cell</td>
+           </tr>
+           <tr>
+             <td align="left">left aligned cell</td>
+             <td align="left">cell</td>
+           </tr>
+           <tr>
+             <td align="right">right aligned cell</td>
+             <td align="left">cell</td>
+           </tr>
+           <tr>
+             <td align="left">foot</td>
+             <td align="left">foot</td>
+           </tr>
+         </tbody>
+      </table>
+      </section>
+    OUTPUT
+  end
+end

data/spec/asciidoctor/rfc/v3/ulist_spec.rb

@@ -0,0 +1,74 @@
+require "spec_helper"
+describe Asciidoctor::RFC::V3::Converter do
+  it "renders an unordered list" do
+    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3)).to be_equivalent_to <<~'OUTPUT'
+      [[id]]
+      [empty=true,spacing=compact]
+      * First
+      * Second
+    INPUT
+      <ul anchor="id" empty="true" spacing="compact">
+      <li>First</li>
+      <li>Second</li>
+      </ul>
+    OUTPUT
+  end
+
+  it "ignores anchors on list items" do
+    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3)).to be_equivalent_to <<~'OUTPUT'
+      [[id]]
+      * First
+      * [[id1]] Second
+    INPUT
+      <ul anchor="id">
+      <li>First</li>
+      <li> Second</li>
+      </ul>
+    OUTPUT
+  end
+
+  it "renders a nested unordered list" do
+    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3)).to be_equivalent_to <<~'OUTPUT'
+      [[id]]
+      * First
+      * Second
+      ** Third
+      ** Fourth
+      * Fifth
+      * Sixth
+    INPUT
+      <ul anchor="id">
+      <li>First</li>
+      <li><t>Second</t>
+      <ul>
+      <li>Third</li>
+      <li>Fourth</li>
+      </ul>
+      </li>
+      <li>Fifth</li>
+      <li>Sixth</li>
+      </ul>
+    OUTPUT
+  end
+
+  it "renders a nested ordered/unordered list" do
+    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3)).to be_equivalent_to <<~'OUTPUT'
+      [[id]]
+      * First
+      * Second
+      [lowerroman]
+      .. Third
+      .. Fourth
+    INPUT
+      <ul anchor="id">
+      <li>First</li>
+      <li><t>Second</t>
+      <ol type="i">
+      <li>Third</li>
+      <li>Fourth</li>
+      </ol>
+      </li>
+      </ul>
+    OUTPUT
+  end
+end

data/spec/asciidoctor/rfc/v3/workgroup_spec.rb

@@ -0,0 +1,33 @@
+require "spec_helper"
+describe Asciidoctor::RFC::V3::Converter do
+  it "renders workgroups" do
+    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3, header_footer: true)).to be_equivalent_to <<~'OUTPUT'
+      = Document title
+      :docName:
+      Author
+      :workgroup: first_workgroup, second_workgroup
+
+      == Section 1
+      Text
+    INPUT
+      <?xml version="1.0" encoding="US-ASCII"?>
+      <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+
+      <rfc prepTime="2000-01-01T05:00:00Z" version="3" submissionType="IETF">
+      <front>
+      <title>Document title</title>
+      <author fullname="Author">
+      </author>
+      <date day="1" month="January" year="2000"/>
+      <workgroup>first_workgroup</workgroup>
+      <workgroup>second_workgroup</workgroup>
+      </front><middle>
+      <section anchor="_section_1" numbered="false">
+      <name>Section 1</name>
+      <t>Text</t>
+      </section>
+      </middle>
+      </rfc>
+    OUTPUT
+  end
+end

data/spec/examples/davies-template-bare-06.adoc

@@ -0,0 +1,361 @@
+= Put Your Internet Draft Title Here
+Elwyn Davies <elwynd@dial.pipex.com>
+:doctype: internet-draft
+:name: draft-ietf-xml2rfc-template-06
+:ipr: trust200902
+:status: info
+:abbrev: Abbreviated Title
+:fullname: Elwyn Davies
+:forename_initials: E.B.
+:role: editor
+:surname: Davies
+:organization: Folly Consulting
+:city: Soham
+:country: UK
+:phone: +44 7889 488 335
+:email: elwynd@dial.pipex.com
+:revdate: 2010-04-01
+:area: General
+:workgroup: Internet Engineering Task Force
+:keyword: template
+
+[abstract]
+Insert an abstract: MANDATORY. This template is for creating an
+Internet Draft.
+
+== Introduction
+
+The original specification of xml2rfc format is in <<RFC2629,RFC 2629>>.
+
+=== Requirements Language
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+document are to be interpreted as described in <<RFC2119,RFC 2119>>.
+
+[[simple_list]]
+== Simple List
+
+List styles: 'empty', 'symbols', 'letters', 'numbers', 'hanging',
+'format'.
+
+* First bullet
+
+* Second bullet
+
+You can write text here as well.
+//[Note: Asciidoc will force new paragraph]
+
+== Figures
+
+Figures should not exceed 69 characters wide to allow for the indent
+of sections.
+
+[[xml_happy]]
+[align=center]
+====
+Preamble text - can be omitted or empty.
+
+[align=left]
+....
++-----------------------+
+| Use XML, be Happy :-) |
+|_______________________|
+....
+
+Cross-references allowed in pre- and postamble. <<min_ref>>.
+====
+
+The CDATA means you don't need to escape meta-characters (especially
+< (\&lt;) and & (\&amp;)) but is not essential.
+Figures may also have a title attribute but it won't be displayed unless
+there is also an anchor. White space, both horizontal and vertical, is
+significant in figures even if you don't use CDATA.
+
+== Subsections and Tables
+
+=== A Subsection
+
+By default 3 levels of nesting show in table of contents but that
+can be adjusted with the value of the "tocdepth" processing
+instruction.
+
+=== Tables
+
+pass:[..] are very similar to figures:
+
+//[Note: Asciidoc does not support preambles and postambles within tables.]
+
+Tables use ttcol to define column headers and widths. Every cell then has a "c" element for its content.
+
+[[table_example]]
+.A Very Simple Table
+[cols="2*^", frame="sides", grid="cols"]
+|===
+|ttcol #1 |ttcol #2
+
+|c #1 |c #2
+|c #3 |c #4
+|c #5 |c #6
+|===
+
+which is a very simple example.
+
+[[nested_lists]]
+== More about Lists
+Lists with 'hanging labels': the list item is indented the amount of
+the hangIndent:
+
+[hang-indent=8]
+short:: With a label shorter than the hangIndent.
+
+fantastically long label:: With a label longer than the hangIndent.
+
+vspace_trick:: {blank} +
+Forces the new item to start on a new line.
+
+Simulating more than one paragraph in a list item using
+<vspace>:
+
+[loweralpha]
+. First, a short item.
+
+. Second, a longer list item.
++
+{blank}
++
+And something that looks like a separate pararaph..
+
+NOTE: In Asciidoc, it *is* a separate paragraph.
+
+Simple indented paragraph using the "empty" style:
+
+[empty,hang-indent=8]
+* The quick, brown fox jumped over the lazy dog and lived to fool
+         many another hunter in the great wood in the west.
+
+
+=== Numbering Lists across Lists and Sections
+Numbering items continuously although they are in separate
+<list> elements, maybe in separate sections using the "format"
+style and a "counter" variable.
+
+First list:
+
+[hang-indent=4,counter=reqs,format=R%d]
+. #1
+
+. #2
+
+. #3
+
+Specify the indent explicitly so that all the items line up
+nicely.
+
+Second list:
+[hang-indent=4,counter=reqs,format=R%d]
+. #4
+
+. #5
+
+. #6
+
+=== Where the List Numbering Continues
+List continues here.
+
+Third list:
+[hang-indent=4,counter=reqs,format=R%d]
+. #7
+
+. #8
+
+. #9
+
+. #10
+
+The end of the list.
+
+[[codeExample]]
+== Example of Code or MIB Module To Be Extracted
+
+// NOTE: in asciidoctor-rfc output we're missing an empty line before
+// the code block and after it. Can't figure out a way to create that...
+
+====
+The <artwork> element has a number of extra attributes
+that can be used to substitute a more aesthetically pleasing rendition
+into HTML output while continuing to use the ASCII art version in the
+text and nroff outputs (see the xml2rfc README for details). It also
+has a "type" attribute. This is currently ignored except in the case
+'type="abnf"'. In this case the "artwork" is expected to contain a
+piece of valid Augmented Backus-Naur Format (ABNF) grammar. This will
+be syntax checked by xml2rfc and any errors will cause a fatal error
+if the "strict" processing instruction is set to "yes". The ABNF will
+also be colorized in HTML output to highlight the syntactic
+components. Checking of additional "types" may be provided in future
+versions of xml2rfc.
+
+----
+
+
+/**** an example C program */
+
+#include <stdio.h>
+
+void
+main(int argc, char *argv[])
+{
+   int i;
+
+   printf("program arguments are:\n");
+   for (i = 0; i < argc; i++) {
+       printf("%d: \"%s\"\n", i, argv[i]);
+   }
+
+   exit(0);
+} /* main */
+
+/* end of file */
+
+
+----
+====
+
+[[Acknowledgements]]
+== Acknowledgements
+This template was derived from an initial version written by Pekka Savola and contributed by him to the xml2rfc project.
+
+This document is part of a plan to make xml2rfc indispensable <<DOMINATION>>.
+
+[[IANA]]
+== IANA Considerations
+This memo includes no request to IANA.
+
+All drafts are required to have an IANA considerations section (see
+<<RFC5226,Guidelines for Writing an IANA Considerations Section in RFCs>> for a guide). If the draft does not require IANA to do
+anything, the section contains an explicit statement that this is the
+case (as above). If there are no requirements for IANA, the section will
+be removed during conversion into an RFC by the RFC Editor.
+
+[[Security]]
+== Security Considerations
+All drafts are required to have a security considerations section.
+See <<RFC3552,RFC 3552>> for a guide.
+
+
+[bibliography]
+== Normative References
+++++
+
+<reference  anchor='RFC2119' target='https://www.rfc-editor.org/info/rfc2119'>
+<front>
+<title>Key words for use in RFCs to Indicate Requirement Levels</title>
+<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
+<date year='1997' month='March' />
+<abstract><t>In many standards track documents several words are used to signify the requirements in the specification.  These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
+</front>
+<seriesInfo name='BCP' value='14'/>
+<seriesInfo name='RFC' value='2119'/>
+<seriesInfo name='DOI' value='10.17487/RFC2119'/>
+</reference>
+
+<reference anchor="min_ref">
+ <!-- the following is the minimum to make xml2rfc happy -->
+
+ <front>
+   <title>Minimal Reference</title>
+
+   <author initials="authInitials" surname="authSurName">
+     <organization></organization>
+   </author>
+
+   <date year="2006" />
+ </front>
+</reference>
+++++
+
+[bibliography]
+== Informative References
+++++
+<!-- Here we use entities that we defined at the beginning. -->
+
+<reference  anchor='RFC2629' target='https://www.rfc-editor.org/info/rfc2629'>
+<front>
+<title>Writing I-Ds and RFCs using XML</title>
+<author initials='M.' surname='Rose' fullname='M. Rose'><organization /></author>
+<date year='1999' month='June' />
+<abstract><t>This memo presents a technique for using XML (Extensible Markup Language) as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series.  This memo provides information for the Internet community.</t></abstract>
+</front>
+<seriesInfo name='RFC' value='2629'/>
+<seriesInfo name='DOI' value='10.17487/RFC2629'/>
+</reference>
+
+<reference  anchor='RFC3552' target='https://www.rfc-editor.org/info/rfc3552'>
+<front>
+<title>Guidelines for Writing RFC Text on Security Considerations</title>
+<author initials='E.' surname='Rescorla' fullname='E. Rescorla'><organization /></author>
+<author initials='B.' surname='Korver' fullname='B. Korver'><organization /></author>
+<date year='2003' month='July' />
+<abstract><t>All RFCs are required to have a Security Considerations section. Historically, such sections have been relatively weak.  This document provides guidelines to RFC authors on how to write a good Security Considerations section.   This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
+</front>
+<seriesInfo name='BCP' value='72'/>
+<seriesInfo name='RFC' value='3552'/>
+<seriesInfo name='DOI' value='10.17487/RFC3552'/>
+</reference>
+
+<reference  anchor='RFC5226' target='https://www.rfc-editor.org/info/rfc5226'>
+<front>
+<title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
+<author initials='T.' surname='Narten' fullname='T. Narten'><organization /></author>
+<author initials='H.' surname='Alvestrand' fullname='H. Alvestrand'><organization /></author>
+<date year='2008' month='May' />
+<abstract><t>Many protocols make use of identifiers consisting of constants and other well-known values.  Even after a protocol has been defined and deployment has begun, new values may need to be assigned (e.g., for a new option type in DHCP, or a new encryption or authentication transform for IPsec).  To ensure that such quantities have consistent values and interpretations across all implementations, their assignment must be administered by a central authority.  For IETF protocols, that role is provided by the Internet Assigned Numbers Authority (IANA).</t><t>In order for IANA to manage a given namespace prudently, it needs guidelines describing the conditions under which new values can be assigned or when modifications to existing values can be made.  If IANA is expected to play a role in the management of a namespace, IANA must be given clear and concise instructions describing that role.  This document discusses issues that should be considered in formulating a policy for assigning values to a namespace and provides guidelines for authors on the specific text that must be included in documents that place demands on IANA.</t><t>This document obsoletes RFC 2434.  This document specifies an Internet Best  Current Practices for the Internet Community, and requests discussion and  suggestions for improvements.</t></abstract>
+</front>
+<seriesInfo name='RFC' value='5226'/>
+<seriesInfo name='DOI' value='10.17487/RFC5226'/>
+</reference>
+
+
+<!-- A reference written by by an organization not a person. -->
+
+<reference anchor="DOMINATION"
+           target="http://www.example.com/dominator.html">
+  <front>
+    <title>Ultimate Plan for Taking Over the World</title>
+
+    <author>
+      <organization>Mad Dominators, Inc.</organization>
+    </author>
+
+    <date year="1984" />
+  </front>
+</reference>
+++++
+
+[[app-additional]]
+[appendix]
+== Additional Stuff
+This becomes an Appendix.
+
+////
+   <!-- Change Log
+
+v00 2006-03-15  EBD   Initial version
+
+v01 2006-04-03  EBD   Moved PI location back to position 1 -
+                     v3.1 of XMLmind is better with them at this location.
+v02 2007-03-07  AH    removed extraneous nested_list attribute,
+                     other minor corrections
+v03 2007-03-09  EBD   Added comments on null IANA sections and fixed heading capitalization.
+                     Modified comments around figure to reflect non-implementation of
+                     figure indent control.  Put in reference using anchor="DOMINATION".
+                     Fixed up the date specification comments to reflect current truth.
+v04 2007-03-09 AH     Major changes: shortened discussion of PIs,
+                     added discussion of rfc include.
+v05 2007-03-10 EBD    Added preamble to C program example to tell about ABNF and alternative
+                     images. Removed meta-characters from comments (causes problems).
+
+v06 2010-04-01 TT     Changed ipr attribute values to latest ones. Changed date to
+                     year only, to be consistent with the comments. Updated the
+                     IANA guidelines reference from the I-D to the finished RFC.  -->
+////