asciidoctor-rfc 0.2.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 353275d1f9b667ea2df54f92a86642af08bde911
-  data.tar.gz: 2aa84d1157db6239f7687a08a8ec31875bf41e21
+  metadata.gz: 35f7a1bd23b6de975c31f813b3c706bacd397143
+  data.tar.gz: cf7b2e21d14bfe6adcea630187d47ecf894299ff
 SHA512:
-  metadata.gz: b95ea46b72fefc3d8a2c6a5176ae8bafc4973382de800508821c41b3a54f739d56397f84ca13e6d752ce48eb3e62064bbe7ff807c9666275ceda324e519b2a09
-  data.tar.gz: 06c7157614ed91107958b46a6f1d8e7aacd910b6886a1c88e37e95c07d4ef7eeb9b9010469fb24140aa81fb9d15e56f0443ff5b7d9142455015143127c2e661e
+  metadata.gz: c482a9f84673ef72e87ede4096ee1584a90c1df3be25cdc73e49cc243a3e336289d8b1f58cd036625fac5e8fa5a7006d41e523bc8d6fde26cac6edbc01a0fb7e
+  data.tar.gz: 9f8d197aa2f9ec92af349ca550a6f4b8a423ca090d597481932fefc2694c835c744feee74b2fb16870d6eb98e120cd5d337a8bd8ecf872c2d1361a37536a0881

data/README.adoc

@@ -62,7 +62,7 @@ David Waitzman <dwaitzman@BBN.COM>
 :abbrev: IP Datagrams on Avian Carriers
 :obsoletes: 10, 120
 :updates: 2010, 2120
-:status: info
+:status: informational
 :name: internet-draft-avian-transmission-00
 :ipr: trust200902
 :area: Internet
@@ -103,7 +103,27 @@ paradoxically, generally increases with increased carrier age.  A
 typical MTU is 256 milligrams.  Some datagram padding may be needed.<<RFC7253>>
 
 [bibliography]
-== References
+== 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>
+++++
+
+[bibliography]
+== Informative References
 ++++
 <reference anchor='RFC7253' target='https://tools.ietf.org/html/rfc7253'>
   <front>
@@ -213,6 +233,14 @@ Permit smart quotes, when they are specified explicitly in Asciidoc (as `"`...`"
 When disabled, smart quotes are rendered as straight quotes, and Asciidoc's default conversion
 of straight apostrophes to smart is undone.
 
+|`:inline-definition-lists:`
+|Optional. Default value `false`. Allowed values: `true`, `false`.
+Only applies to v2. By default, `<vspace blankLines="1">` is inserted after
+the definition in a v2 definition list, to satisfy the requirement from `idnits` validation
+that definition terms be separated by a carriage return from the definition. That is, by
+default inline definition lists are rendered as paragraphing definition lists. If the option is
+on, the additional `vspace` element is not added, and inline definition lists are left as is..
+
 |===
 
 
@@ -295,6 +323,57 @@ metadata.
 
 |===
 
+=== Processing Instructions
+The `xml2rfc` tool accepts processing instructions of the form `<?rfc keyword='value'?>`:
+see https://xml2rfc.tools.ietf.org/authoring/README.html#processing.instructions .
+(Of these, `sort-refs`, `sym-refs` and `toc-include`  are also present in the 
+v3 RFC XML specifcation, as attributes of the
+root `rfc` element: <<v3documentattributes,v3-specific document attributes>>.)
+Those processing instructions which apply to the entire document can also be 
+specified for this gem as document options. 
+
+|===
+|keyword |meaning
+
+|artworkdelimiter |	when producing txt or nroff files, use this string to delimit artwork
+|artworklines |	when producing txt or nroff files, add this many blank lines around artwork
+|authorship |	render author information
+|autobreaks |	automatically force page breaks to avoid widows and orphans (not perfect)
+|background |	when producing a html file, use this image
+|colonspace |	put two spaces instead of one after each colon (":") in txt or nroff files
+|comments |	render <cref> information
+|compact |	when producing a txt/nroff file, try to conserve vertical whitespace (the default value is the current value of the rfcedstyle PI)
+|docmapping |	use hierarchical tags (e.g., <h1>, <h2>, etc.) for (sub)section titles
+|editing |	insert editing marks for ease of discussing draft versions
+|emoticonic |	automatically replaces input sequences such as \|*text\| by, e.g., <strong>text</strong> in html output
+|footer |	override the center footer string
+|header |	override the leftmost header string
+|inline |	if comments is "yes", then render comments inline; otherwise render them in an "Editorial Comments" section
+|iprnotified |	include boilerplate from Section 10.4(d) of http://tools.ietf.org/html/rfc2026
+|linkmailto |	generate mailto: URL, as appropriate
+|linefile |	a string like "35:file.xml" or just "35" (file name then defaults to the containing file's real name or to the latest linefile specification that changed it) that will be used to override xml2rfc's reckoning of the current input position (right after this PI) for warning and error reporting purposes (line numbers are 1-based)
+|notedraftinprogress |	generates "(work in progress)", as appropriate
+|private |	produce a private memo rather than an RFC or Internet-Draft
+|refparent |	title of the top-level section containing all references
+|rfcedstyle |	attempt to closely follow finer details from the latest observable RFC-Editor style so as to minimize the probability of being sent back corrections after submission; this directive is a kludge whose exact behavior is likely to change on a regular basis to match the current flavor of the month; presently, it will capitalize the adjective "This" in automatically generated headings, use the variant "acknowledgement" spelling instead of Merriam Webster's main "acknowledgment" dictionary entry, use the "eMail" spelling instead of Knuth's more modern "email" spelling, only put one blank line instead of two before top sections, omit "Intellectual Property and Copyright Statements" and "Author's Address" from the table of content, and not limit the indentation to a maximum tag length in <references> sections.
+|rfcprocack |	if there already is an automatically generated Acknowledg(e)ment section, pluralize its title and add a short sentence acknowledging that xml2rfc was used in the document's production to process an input XML source file in RFC-2629 format
+|slides |	when producing a html file, produce multiple files for a slide show
+|sort-refs |	(`sortrefs`) sort references
+|strict |	try to enforce the ID-nits conventions and DTD validity
+|subcompact |	if compact is "yes", then you can make things a little less compact by setting this to "no" (the default value is the current value of the compact PI)
+|sym-refs |	(`symrefs`) use anchors rather than numbers for references
+|text-list-symbols |	modify the list of symbols used (when generated text) for list type="symbols". For example, specifying "abcde" will cause "a" to be used for 1st level, "b" for the 2nd level, etc, cycling back to the first character "a" at the 6th level. Specifying "o*" will cause the characters "o" and "*" to be alternated for each successive level.
+|toc-include |	(`toc`) generate a table-of-contents
+|tocappendix |	control whether the word "Appendix" appears in the table-of-content
+|tocdepth |	if toc is "yes", then this determines the depth of the table-of-contents
+|tocindent |	if toc is "yes", then setting this to "yes" will indent subsections in the table-of-contents
+|tocnarrow |	affects horizontal spacing in the table-of-content
+|tocompact |	if toc is "yes", then setting this to "no" will make it a little less compact
+|topblock |	put the famous header block on the first page
+|useobject |	when producing a html file, use the <object> html element with inner replacement content instead of the <img> html element, when a source xml element includes an src attribute
+|===
+
+Exceptionally, `compact`, `toc-include`, `sym-refs`, `sort-refs` and `strict` are is set by default to `yes`, `subcompact` to `no`, and `toc-depth` to 4.
 
 === Document Name / Number (Mandatory)
 
@@ -318,6 +397,9 @@ When `doctype` is set to:
 
 Set the `status` attribute to set the current status of this document.
 
+The following values are allowed: `standard`, `informational`, `experimental`, `bcp`, `fyi`, 
+`full-standard` (v3 only), `historic` (v2 only).  
+
 * In v3, this sets the first `front/seriesInfo` element with `@status` as one
   of: `standard`, `informational`, `experimental`, `bcp`, `fyi`, `full-standard`.
 * In v2, this sets the `rfc@category` value as one of `std`, `info`, `exp`, `bcp`, `historic`.
@@ -392,6 +474,7 @@ These attributes are only supported for the v2 converter.
 | `rfc@seriesNo`
 |===
 
+[#v3documentattributes]
 === Document Attributes for v3 only
 
 These attributes are only supported for the v3 converter.
@@ -411,18 +494,18 @@ formatter should include an index in generated files. If the source file has no
 
 |`:sort-refs:`
 | Optional. Defaults to `false`. Values: `true` or `false`. Specifies whether
-the prep tool should sort references.
+the prep tool should sort references. Supported in v2 as a processing instruction.
 | `rfc@sortRefs`
 
 |`:sym-refs:`
 | Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether
 formatter should use symbolic references (such as "`[RFC2119]`") or not
-(such as "`[3]`").
+(such as "`[3]`"). Supported in v2 as a processing instruction.
 | `rfc@symRefs`
 
 |`:toc-include:`
 | Optional. Defaults to `true`. Values: `true` or `false`. Specifies whether
-formatter should contain a table of contents.
+formatter should contain a table of contents. Supported in v2 as a processing instruction.
 | `rfc@tocInclude`
 
 | `:link{_i_}: _URL_` or `:link{_i_}: _URL_ _REL_`
@@ -484,6 +567,9 @@ These will be mapped as follows:
 
 |===
 
+If any author names deviate from that pattern, e.g. with an honorific like Dr.,
+they will not be recognised correctly by the Asciidoc API; use the `fullname`
+document attribute instead.
 
 ==== Author Attributes
 
@@ -739,6 +825,7 @@ _Italic_ <2>
 ^superscript^ <6>
 [bcp14]#MUST NOT# <7>
 *MUST NOT* <8>
+stem:[sqrt(4) = 2]
 --
 <1> That is, "+ " at the end of a line. v3: `<br/>`; v2: `<vspace/>`.
 <2> v3: `<em>Italic</em>`; v2: `<spanx style="emph">Italic</spanx>`
@@ -748,6 +835,7 @@ _Italic_ <2>
 <6> v3 only: `<sup>superscript</sup>`. Not supported in v2; rendered as `\^superscript^`
 <7> v3 only: `<bcp14>MUST NOT</bcp14>`. Not supported in v2; rendered as `<spanx style="strong">MUST NOT</spanx>`.
 <8> v3: if document flag `:no-rfc-bold-bcp14:` is present, then `<strong>MUST NOT</strong>`, else (by default) any BCP14/RFC2119 phrase in boldface and capitals is assumed to be intended to be tagged in `<bcp14>`. v2: `<spanx style="strong">MUST NOT</spanx>`.
+<9> Stem expressions are treated identically to monospace expressions; they are not currently rendered as MathML or any other notation.
 
 NOTE: The delimiters must occur within the one line; the following is invalid in Asciidoctor:
 [source,asciidoc]
@@ -859,6 +947,21 @@ Postamble text <11>
 <10> `figure/artwork@src`, `figure/artwork@alt`, `figure/artwork@width` (deprecated in v3), `figure/artwork@height` (deprecated in v3)
 <11> v2 only: `figure/postamble` (only available in v2)
 
+=== Mathematical examples
+
+[source,asciidoc]
+--
+:stem:
+
+[stem]
+++++
+sqrt(4) = 2
+++++
+--
+
+Mathematical examples are treated identically to literals, and are rendered as `artwork` in both v2 and v3;
+however their default alignment is set as `center`. As with inline stem expressions, they are treated identically 
+to monospace expressions; they are not currently rendered as MathML or any other notation.
 
 === Unordered and Ordered Lists
 
@@ -910,6 +1013,10 @@ A:: B <3>
 NOTE: Asciidoctor does not permit anchors on either definition list terms,
 or definition list definitions: the anchors in the following are ignored.
 
+NOTE: In RFC XML v2, `idnits` considers inline definition lists invalid; the gem
+renders them as paragraphed definition lists. The gem option `:inline-definition-lists`
+disables this behaviour.
+
 [source,asciidoc]
 --
 [[id1]] A:: [[id2]]B
@@ -973,6 +1080,10 @@ to populate `displayreference` elements, mapping the reference anchors to displa
 a list entry `[[[ref1,alt1]]]` means that any instances of the anchor `ref1` should be displayed as `alt1`,
 and is rendered as `<displayreference target="ref1" to="alt1"/>`.
 
+RFC requires two separate bibliographies, one for normative and one for informative references;
+either can be omitted. All bibliography sections in the must be styled with the prefix `[bibliography]`,
+and must appear in sequence, before any appendices.
+
 [source,asciidoc]
 --
 [[id]] <1>
@@ -995,7 +1106,6 @@ and is rendered as `<displayreference target="ref1" to="alt1"/>`.
 <3> `back/references/reference`
 
 
-
 === Appendices
 
 [source,asciidoc]

data/asciidoctor-rfc.gemspec

@@ -10,8 +10,22 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Ribose Inc."]
   spec.email         = ["open.source@ribose.com"]
 
-  spec.summary       = "todo: AsciiDoctorRFC summary."
+  spec.summary       = 'asciidoctor-rfc lets you write Internet-Drafts and RFCs in AsciiDoc.'
   spec.description   = <<~DESCRIPTION
+asciidoctor-rfc lets you write Internet-Drafts and RFCs in a native
+"asciidoctor" syntax.
+
+RFC XML ("xml2rfc" Vocabulary XML, RFC7322) is the XML-based language used for
+writing Internet-Drafts and RFCs, but not everyone likes hand-crafting XML,
+especially when the focus should be on the content.
+
+Specifically, the gem provides two things. First, an "asciidoctor" like syntax
+that lets you utilize close to all features of native RFC XML, and maps most
+asciidoctor textual syntax (like tables) into RFC XML features. Then, RFC XML
+v3 (RFC 7991) and v2 (RFC 7749) backends that lets you render your AsciiDoc
+into, you guessed it, RFC XML v3 and v2.
+
+This gem is in active development.
   DESCRIPTION
 
   spec.homepage      = "https://github.com/riboseinc/asciidoctor-rfc"

data/lib/asciidoctor/rfc/common/base.rb

@@ -148,13 +148,75 @@ module Asciidoctor
             result << send(b.context, b)
           end
         else
-          result << paragraph(node)
+          result = paragraph(node)
         end
         result
       end
 
-      def dash(camel_cased_word)
-        camel_cased_word.gsub(/([a-z])([A-Z])/, '\1-\2').downcase
+      #def dash(camel_cased_word)
+      #  camel_cased_word.gsub(/([a-z])([A-Z])/, '\1-\2').downcase
+      #end
+
+      def common_rfc_pis(node)
+        # Below are generally applicable Processing Instructions (PIs)
+        # that most I-Ds might want to use, common to v2 and v3.
+        # These are set only if explicitly specified, with the exception
+        # of compact and subcompact
+        rfc_pis = {
+            artworkdelimiter: node.attr("artworkdelimiter"),
+            artworklines: node.attr("artworklines"),
+            authorship: node.attr("authorship"),
+            autobreaks: node.attr("autobreaks"),
+            background: node.attr("background"),
+            colonspace: node.attr("colonspace"),
+            comments: node.attr("comments"),
+            docmapping: node.attr("docmapping"),
+            editing: node.attr("editing"),
+            emoticonic: node.attr("emoticonic"),
+            footer: node.attr("footer"),
+            header: node.attr("header"),
+            inline: node.attr("inline"),
+            iprnotified: node.attr("iprnotified"),
+            linkmailto: node.attr("linkmailto"),
+            linefile: node.attr("linefile"),
+            notedraftinprogress: node.attr("notedraftinprogress"),
+            private: node.attr("private"),
+            refparent: node.attr("refparent"),
+            rfcedstyle: node.attr("rfcedstyle"),
+            slides: node.attr("slides"),
+            "text-list-symbols": node.attr("text-list-symbols"),
+            tocappendix: node.attr("tocappendix"),
+            tocindent: node.attr("tocindent"),
+            tocnarrow: node.attr("tocnarrow"),
+            tocompact: node.attr("tocompact"),
+            topblock: node.attr("topblock"),
+            useobject: node.attr("useobject"),
+
+          # give errors regarding ID-nits and DTD validation
+            strict: node.attr("strict") || "yes",
+
+          # Vertical whitespace control
+          # (using these PIs as follows is recommended by the RFC Editor)
+
+          # do not start each main section on a new page
+            compact: node.attr("compact") || "yes",
+          # keep one blank line between list items
+            subcompact: node.attr("subcompact") || "no",
+
+          # TOC control
+          # generate a ToC
+          toc: node.attr("toc-include") == "false" ? "no" : "yes",
+
+          # the number of levels of subsections in ToC. default: 3
+          tocdepth: node.attr("toc-depth") || "4",
+
+          # use anchors rather than numbers for references
+          symrefs: node.attr("sym-refs") || "yes",
+          # sort references
+          sortrefs: node.attr("sort-refs") || "yes",
+        }
+
+        attr_code(rfc_pis)
       end
 
       # if node contains blocks, flatten them into a single line
@@ -172,16 +234,21 @@ module Asciidoctor
       # if node contains blocks, flatten them into a single line; and extract only raw text
       def flatten_rawtext(node)
         result = []
-        if node.blocks?
+        if node.respond_to?(:blocks) && node.blocks?
           node.blocks.each { |b| result << flatten_rawtext(b) }
         elsif node.respond_to?(:lines)
           node.lines.each do |x|
-            result << x.gsub(/</, "&lt;").gsub(/>/, "&gt;")
+            if node.respond_to?(:context) && (node.context == :literal || node.context == :listing)
+              result << x.gsub(/</, "&lt;").gsub(/>/, "&gt;")
+            else
+              # strip not only HTML tags <tag>, but also Asciidoc crossreferences <<xref>>
+              result << x.gsub(/<[^>]*>+/, "")
+            end
           end
         elsif node.respond_to?(:text)
-          result << node.text.gsub(/<[^>]*>/, "")
+          result << node.text.gsub(/<[^>]*>+/, "")
         else
-          result << node.content.gsub(/<[^>]*>/, "")
+          result << node.content.gsub(/<[^>]*>+/, "")
         end
         result.reject(&:empty?)
       end

data/lib/asciidoctor/rfc/common/front.rb

@@ -75,7 +75,7 @@ module Asciidoctor
 
       def date1(revdate, xml)
         revdate.gsub!(/T.*$/, "")
-        if revdate.length == 4
+        if revdate.length == 4 && revdate =~ /^\d\d\d\d$/
           date_attributes = {
             year: revdate,
           }

data/lib/asciidoctor/rfc/v2/base.rb

@@ -35,6 +35,7 @@ module Asciidoctor
         $seen_back_matter = false
         $seen_abstract = false
         $smart_quotes = (node.attr("smart-quotes") != "false")
+        $inline_definition_lists = (node.attr("inline-definition-lists") == "true")
 
         result = []
         result << '<?xml version="1.0" encoding="UTF-8"?>'
@@ -46,11 +47,16 @@ module Asciidoctor
           "true" => "yes",
         }[node.attr("consensus")] || node.attr("consensus")
 
+        category = node.attr("status")
+        category = "info" if category == "informational"
+        category = "std" if category == "standard"
+        category = "exp" if category == "experimental"
+
         rfc_attributes = {
           ipr:            node.attr("ipr"),
           obsoletes:      node.attr("obsoletes"),
           updates:        node.attr("updates"),
-          category:       node.attr("status"),
+          category:       category,
           consensus:      consensus_value,
           submissionType: node.attr("submission-type") || "IETF",
           iprExtract:     node.attr("ipr-extract"),
@@ -158,7 +164,7 @@ module Asciidoctor
 
         result << noko do |xml|
           xml.t **attr_code(t_attributes) do |xml_t|
-            xml_t << node.content.gsub("\n", "<vspace/>\n")
+            xml_t << node.content.gsub("\n\n", "<vspace blankLines=\"1\"/>").gsub("\n", "<vspace/>\n")
           end
         end
 
@@ -171,12 +177,17 @@ module Asciidoctor
       #   Content
       #
       #   [bibliography]
-      #   == Normative|Informative References
-      #   * [[[ref1]]] Ref [must provide references as list]
-      #   * [[[ref2]]] Ref
+      #   == References
+      #
+      #   [bibliography]
+      #   === Normative|Informative References
+      #   ++++
+      #   RFC XML references
+      #   ++++
       def section(node)
         result = []
-        if node.attr("style") == "bibliography"
+        if node.attr("style") == "bibliography" ||
+            node.parent.context == :section && node.parent.attr("style") == "bibliography"
           $xreftext = {}
           $processing_reflist = true
 
@@ -184,11 +195,25 @@ module Asciidoctor
             title: node.title,
           }
 
+          node.blocks.each do |block|
+            if block.context == :section
+              result << node.content
+            elsif block.context == :pass
+              # we are assuming a single contiguous :pass block of XML
+              result << noko do |xml|
+                xml.references **attr_code(references_attributes) do |xml_references|
+                  xml_references << reflist(block).join
+                end
+              end
+            end
+          end
+=begin
           result << noko do |xml|
             xml.references **attr_code(references_attributes) do |xml_references|
               node.blocks.each { |b| xml_references << reflist(b).join }
             end
           end
+=end
 
           result = result.unshift("</middle><back>") unless $seen_back_matter
           $processing_reflist = false
@@ -248,9 +273,10 @@ module Asciidoctor
         xmldoc = Nokogiri::XML(doc) do |config|
           config.noent
         end
-        crefs = xmldoc.xpath("//cref")
+
         # any crefs that are direct children of section should become children of the preceding
         # paragraph, if it exists; otherwise, they need to be wrapped in a paragraph
+        crefs = xmldoc.xpath("//cref")
         crefs.each do |cref|
           if cref.parent.name == "section"
             prev = cref.previous_element
@@ -263,6 +289,10 @@ module Asciidoctor
             end
           end
         end
+
+        xmldoc.root = merge_vspace(xmldoc.root)
+
+        # smart quotes: handle smart apostrophe
         unless $smart_quotes
           xmldoc.traverse do |node|
             if node.text?
@@ -281,38 +311,53 @@ module Asciidoctor
         xmldoc.to_xml(encoding: "US-ASCII")
       end
 
+      def merge_vspace(node)
+        nodes = []
+        newnodes = []
+        node.children.each do |element|
+          nodes << element
+        end
+
+        counter = 0
+        while counter < nodes.size do
+          if nodes[counter].name == "vspace"
+            blankLines = 0
+            while counter < nodes.size && nodes[counter].name == "vspace" do
+                if nodes[counter][:blankLines].nil?
+                  blankLines += 1
+                else
+                  blankLines +=  nodes[counter][:blankLines].to_i + 1
+                end
+                if counter+1 < nodes.size && nodes[counter+1].text?
+                  if nodes[counter+1].text =~ /\A[\n ]+\Z/m
+                    counter += 1
+                  end
+                end
+                counter += 1
+            end
+            counter -= 1 if counter == nodes.size
+            newnodes << noko do |xml|
+              xml.vspace **attr_code(blankLines: (blankLines - 1))
+            end.join
+          else
+            newnodes << merge_vspace(nodes[counter])
+            nodes[counter].remove
+            counter += 1
+          end
+
+          node.children.remove
+          newnodes.each do |item|
+            node.add_child(item)
+          end
+        end
+        node
+      end
+
       def set_pis(node, doc)
         # Below are generally applicable Processing Instructions (PIs)
         # that most I-Ds might want to use. (Here they are set differently than
         # their defaults in xml2rfc v1.32)
-        rfc_pis = {
-          # give errors regarding ID-nits and DTD validation
-          strict: "yes",
-
-          # TOC control
-          # generate a ToC
-          toc: node.attr("toc-include") == "false" ? "no" : "yes",
-
-          # the number of levels of subsections in ToC. default: 3
-          tocdepth: node.attr("toc-depth") || "4",
-
-          # References control
-
-          # use symbolic references tags, i.e, [RFC2119] instead of [1]
-          symrefs: "yes",
-
-          # sort the reference entries alphabetically
-          sortrefs: "yes",
-
-          # Vertical whitespace control
-          # (using these PIs as follows is recommended by the RFC Editor)
-
-          # do not start each main section on a new page
-          compact: "yes",
-
-          # keep one blank line between list items
-          subcompact: "no",
-        }
+        rfc_pis = common_rfc_pis(node)
 
         doc.create_internal_subset("rfc", nil, "rfc2629.dtd")
         rfc_pis.each_pair do |k, v|
@@ -325,13 +370,17 @@ module Asciidoctor
         doc
       end
 
-      # replace any <t>text</t> instances with <vspace/>text
+      # replace any <t>text</t> instances with <vspace blankLines="1"/>text
       def para_to_vspace(doc)
         xmldoc = Nokogiri::XML("<fragment>#{doc}</fragment>")
         paras = xmldoc.xpath("/fragment/t")
         paras.each do |para|
-          vspace = Nokogiri::XML::Element.new("vspace", xmldoc.document)
-          para.before(vspace)
+          # we do not insert vspace if the para contains a list: space will go there anyway
+          unless para.element_children.size == 1 && para.element_children[0].name == "list"
+            vspace = Nokogiri::XML::Element.new("vspace", xmldoc.document)
+            vspace["blankLines"] = "1"
+            para.before(vspace)
+          end
           para.replace(para.children)
         end
         xmldoc.root.children.to_xml(encoding: "US-ASCII")