asciidoctor-rfc 0.1.0 → 0.2.0

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

@@ -0,0 +1,192 @@
+module Asciidoctor
+  module RFC::V2
+    module Blocks
+      # Syntax:
+      # [discrete]
+      # == Section
+      def floating_title(node)
+        noko do |xml|
+          xml.t do |xml_t|
+            xml_t.spanx node.title, style: "strong"
+          end
+        end
+      end
+
+      # Syntax:
+      #   [[id]]
+      #   .Name
+      #   [align=left|center|right,alt=alt_text,type] (optional)
+      #   ....
+      #     literal
+      #   ....
+      def literal(node)
+        artwork_attributes = {
+          align: node.attr("align"),
+          type: node.attr("type"),
+          name: node.title,
+          alt: node.attr("alt"),
+        }
+
+        # NOTE: html escaping is performed by Nokogiri
+        artwork_content = node.lines.join("\n")
+
+        ret = noko do |xml|
+          if node.parent.context != :example
+            xml.figure do |xml_figure|
+              xml_figure.artwork artwork_content, **attr_code(artwork_attributes)
+            end
+          else
+            xml.artwork artwork_content, **attr_code(artwork_attributes)
+          end
+        end
+        ret
+      end
+
+      # Syntax:
+      #   = Title
+      #   Author
+      #   :HEADER
+      #
+      #   ABSTRACT
+      #
+      #   NOTE: note
+      #
+      #   [NOTE]
+      #   .Title (in preamble)
+      #   ====
+      #     Content
+      #   ====
+      #
+      #     [NOTE] (in preamble)
+      #     [NOTE,source=name] (in body)
+      #   .Title
+      #   ====
+      #     Content
+      #   ====
+      #
+      # @note admonitions within preamble are notes. Elsewhere, they are comments.
+      def admonition(node)
+        result = []
+        if node.parent.context == :preamble
+          if $seen_abstract
+            result << "</abstract>"
+            $seen_abstract = false
+          end
+
+          note_attributes = {
+            # default title provided: title is mandatory
+            title: (node.title.nil? ? "NOTE" : node.title),
+          }
+
+          note_contents = [paragraph1(node)].flatten.join("\n")
+
+          result << noko do |xml|
+            xml.note **attr_code(note_attributes) do |xml_note|
+              xml_note << note_contents
+            end
+          end
+        else
+          cref_attributes = {
+            anchor: node.id,
+            source: node.attr("source"),
+          }
+
+          # remove all formatting: cref content is pure text
+          cref_contents = flatten_rawtext(node)
+          cref_contents = [cref_contents].flatten.join("\n")
+          warn <<~WARNING_MESSAGE if node.blocks?
+            asciidoctor: WARNING: comment can not contain blocks of text in XML RFC:\n #{node.content}
+          WARNING_MESSAGE
+
+          result << noko do |xml|
+            if node.parent.context !~ /table|example|paragraph|section/
+              xml.t do |xml_t|
+                xml_t.cref **attr_code(cref_attributes) do |xml_cref|
+                  xml_cref << cref_contents
+                end
+              end
+            else
+              xml.cref **attr_code(cref_attributes) do |xml_cref|
+                xml_cref << cref_contents
+              end
+            end
+          end
+        end
+        result
+      end
+
+      # Syntax:
+      #   [[id]]
+      #   .Title
+      #   [align,alt,suppress-title]
+      #   ====
+      #   Example
+      #   ====
+      def example(node)
+        figure_attributes = {
+          anchor: node.id,
+          align: node.attr("align"),
+          alt: node.alt,
+          title: node.title,
+          'suppress-title': node.attr("suppress-title"),
+          # TODO: is 'suppress-title' the correct attribute name?
+        }
+        # TODO iref
+        seen_artwork = false
+        noko do |xml|
+          xml.figure **attr_code(figure_attributes) do |xml_figure|
+            node.blocks.each do |b|
+              case b.context
+              when :listing, :image, :literal
+                xml_figure << send(b.context, b).join("\n")
+                seen_artwork = true
+              else
+                # we want to see the para text, not its <t> container
+                if seen_artwork
+                  xml_figure.postamble do |postamble|
+                    postamble << b.content
+                  end
+                else
+                  xml_figure.preamble do |preamble|
+                    preamble << b.content
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+
+      # Syntax:
+      #   .name
+      #   [source,type,src=uri] (src is mutually exclusive with listing content) (v3)
+      #   [source,type,src=uri,align,alt] (src is mutually exclusive with listing content) (v2)
+      #   ----
+      #   code
+      #   ----
+      def listing(node)
+        sourcecode_attributes = {
+          align: node.attr("align"),
+          alt: node.alt,
+          name: node.title,
+          type: node.attr("language"),
+          src: node.attr("src"),
+        }
+
+        # NOTE: html escaping is performed by Nokogiri
+        sourcecode_content =
+          sourcecode_attributes[:src].nil? ? node.lines.join("\n") : ""
+
+        noko do |xml|
+          if node.parent.context != :example
+            xml.figure do |xml_figure|
+              xml_figure.artwork sourcecode_content, **attr_code(sourcecode_attributes)
+            end
+          else
+            xml.artwork sourcecode_content, **attr_code(sourcecode_attributes)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+require "asciidoctor"
+
+require "asciidoctor/rfc/version"
+require "asciidoctor/rfc/common/base"
+require "asciidoctor/rfc/common/front"
+require "asciidoctor/rfc/v2/base"
+require "asciidoctor/rfc/v2/blocks"
+require "asciidoctor/rfc/v2/front"
+require "asciidoctor/rfc/v2/inline_anchor"
+require "asciidoctor/rfc/v2/lists"
+require "asciidoctor/rfc/v2/table"
+require "asciidoctor/rfc/v2/validate"
+
+module Asciidoctor
+  module RFC::V2
+    # A {Converter} implementation that generates RFC XML 2 output, a format used to
+    # format RFC proposals (https://tools.ietf.org/html/rfc7749)
+    #
+    # Features drawn from https://github.com/miekg/mmark/wiki/Syntax and
+    # https://github.com/riboseinc/rfc2md
+    class Converter
+      include ::Asciidoctor::Converter
+      include ::Asciidoctor::Writer
+
+      include ::Asciidoctor::RFC::Common::Base
+      include ::Asciidoctor::RFC::Common::Front
+      include ::Asciidoctor::RFC::V2::Base
+      include ::Asciidoctor::RFC::V2::Blocks
+      include ::Asciidoctor::RFC::V2::Front
+      include ::Asciidoctor::RFC::V2::InlineAnchor
+      include ::Asciidoctor::RFC::V2::Lists
+      include ::Asciidoctor::RFC::V2::Table
+      include ::Asciidoctor::RFC::V2::Validate
+
+      register_for "rfc2"
+
+      $seen_back_matter = false
+      $seen_abstract = false
+      $xreftext = {}
+
+      def initialize(backend, opts)
+        super
+        basebackend "html"
+        outfilesuffix ".xml"
+      end
+
+      # alias_method :pass, :content
+      alias_method :embedded, :content
+      alias_method :sidebar, :content
+      alias_method :audio, :skip
+      alias_method :colist, :skip
+      alias_method :page_break, :skip
+      alias_method :thematic_break, :skip
+      alias_method :video, :skip
+      alias_method :inline_button, :skip
+      alias_method :inline_kbd, :skip
+      alias_method :inline_menu, :skip
+      alias_method :inline_image, :skip
+
+      alias_method :stem, :literal
+      alias_method :quote, :paragraph
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+module Asciidoctor
+  module RFC::V2
+    module Front
+      # Syntax:
+      #   = Title
+      #   Author
+      #   :METADATA
+      def front(node, xml)
+        xml.front do |xml_front|
+          title node, xml_front
+          author node, xml_front
+          date node, xml_front
+          area node, xml_front
+          workgroup node, xml_front
+          keyword node, xml_front
+        end
+      end
+
+      def organization(node, suffix, xml)
+        organization = node.attr("organization#{suffix}")
+        organization_abbrev = node.attr("organization_abbrev#{suffix}")
+        organization_attributes = {
+          abbrev: organization_abbrev,
+        }
+        unless organization.nil?
+          xml.organization **attr_code(organization_attributes) do |org|
+            org << organization
+          end
+        end
+      end
+
+      def address(node, suffix, xml)
+        email = node.attr("email#{suffix}")
+        facsimile = node.attr("fax#{suffix}")
+        phone = node.attr("phone#{suffix}")
+        street = node.attr("street#{suffix}")
+        uri = node.attr("uri#{suffix}")
+
+        # If there is no provided elements for address, don't show it
+        return unless [email, facsimile, phone, street, uri].any?
+
+        # https://tools.ietf.org/html/rfc7749#section-2.27
+        # Note that at least one <street> element needs to be present;
+        # however, formatters will handle empty values just fine.
+        street = street ? street.split("\\ ") : [""]
+
+        xml.address do |xml_address|
+          xml_address.postal do |xml_postal|
+            city = node.attr("city#{suffix}")
+            code = node.attr("code#{suffix}")
+            country = node.attr("country#{suffix}")
+            region = node.attr("region#{suffix}")
+
+            street.each { |st| xml_postal.street { |s| s << st } }
+            xml_postal.city { |c| c << city } unless city.nil?
+            xml_postal.region { |r| r << region } unless region.nil?
+            xml_postal.code { |c| c << code } unless code.nil?
+            xml_postal.country { |c| c << country } unless country.nil?
+          end
+
+          xml_address.phone { |p| p << phone } unless phone.nil?
+          xml_address.facsimile { |f| f << facsimile } unless facsimile.nil?
+          xml_address.email { |e| e << email } unless email.nil?
+          xml_address.uri { |u| u << uri } unless uri.nil?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+module Asciidoctor
+  module RFC::V2
+    module InlineAnchor
+      def inline_anchor(node)
+        case node.type
+        when :xref
+          inline_anchor_xref node
+        when :link
+          inline_anchor_link node
+        when :bibref
+          inline_anchor_bibref node
+        when :ref
+          inline_anchor_ref node
+        else
+          warn %(asciidoctor: WARNING: unknown anchor type: #{node.type.inspect})
+        end
+      end
+
+      private
+
+      def inline_anchor_xref(node)
+        if node.text =~ /^\S+ (of|comma|parens|bare)\b/
+          # <<crossreference#fragment,section (of|comma|parens|bare): text>> = relref:
+          # render equivalent in v2
+          matched = /(?<section>\S+)\s+(?<format>[a-z]+)(: )?(?<text>.*)$/.match node.text
+
+          target = node.target.gsub(/\..*$/, "").gsub(/^#/, "")
+          reftarget = target
+          reftarget = "#{target}##{node.attributes['fragment']}" unless node.attributes["path"].nil?
+
+          xref_contents = case matched[:format]
+                          when "of"
+                            "Section #{matched[:section]} of [#{target}]"
+                          when "comma"
+                            "[#{target}], Section #{matched[:section]}"
+                          when "parens"
+                            "[#{target}] (Section #{matched[:section]})"
+                          when "bare"
+                            matched[:section]
+                          else
+                            "Section #{matched[:section]} of #{target}"
+                          end
+          unless matched[:text].empty?
+            xref_contents = "#{xref_contents}: #{matched[:text]}"
+          end
+
+          xref_attributes = {
+            target: reftarget,
+          }.reject { |_, value| value.nil? }
+
+        else
+
+          matched = /^format=(?<format>counter|title|none|default):\s*(?<text>.*)$/.match node.text
+          xref_contents = matched.nil? ? node.text : matched[:text]
+          matched ||= {}
+
+          xref_attributes = {
+            target: node.target.gsub(/^#/, ""),
+            format: matched[:format],
+            align: node.attr("align"),
+          }
+        end
+
+        noko do |xml|
+          xml.xref xref_contents, **attr_code(xref_attributes)
+        end.join
+      end
+
+      def inline_anchor_link(node)
+        eref_contents = node.target == node.text ? nil : node.text
+
+        eref_attributes = {
+          target: node.target,
+        }
+
+        noko do |xml|
+          xml.eref eref_contents, **attr_code(eref_attributes)
+        end.join
+      end
+
+      def inline_anchor_bibref(node)
+        unless node.xreftext.nil?
+          x = node.xreftext.gsub(/^\[(.+)\]$/, "\\1")
+          if node.id != x
+            $xreftext[node.id] = x
+          end
+        end
+        # NOTE technically node.text should be node.reftext, but subs have already been applied to text
+        %(<bibanchor="#{node.id}">) # will convert to anchor attribute upstream
+      end
+
+      def inline_anchor_ref(node)
+        # If this is within referencegroup, output as bibanchor anyway
+        if $processing_reflist
+          %(<bibanchor="#{node.id}">) # will convert to anchor attribute upstream
+        else
+          warn %(asciidoctor: WARNING: anchor "#{node.id}" is not in a place where XML RFC will recognise it as an anchor attribute)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+module Asciidoctor
+  module RFC::V2
+    module Lists
+      # Syntax:
+      #   * A
+      #   * B
+      def ulist(node)
+        noko { |xml| wrap_list :ulist_naked, node, xml }
+      end
+
+      OLIST_TYPES = Hash.new("numbers").merge(
+        arabic:     "numbers",
+        # decimal:    "1", # not supported
+        loweralpha: "letters",
+        # lowergreek: "lower-greek", # not supported
+        lowerroman: "format %i.",
+        upperalpha: "format %C.",
+        upperroman: "format %I.",
+      ).freeze
+
+      # Syntax:
+      #   [counter=token] (optional)
+      #   . A
+      #   . B
+      def olist(node)
+        noko { |xml| wrap_list :olist_naked, node, xml }
+      end
+
+      # Syntax:
+      #   [hangIndent=n] (optional)
+      #   A:: B
+      #   C:: D
+      def dlist(node)
+        noko { |xml| wrap_list :dlist_naked, node, xml }
+      end
+
+      private
+
+      def wrap_list(method_name, node, xml)
+        if node.parent.context !~ /paragraph|list_item/
+          xml.t do |xml_t|
+            send method_name, node, xml_t
+          end
+        else
+          send method_name, node, xml
+        end
+      end
+
+      def ulist_naked(node, xml)
+        style = "symbols"
+        style = "empty" if node.attr("style") == "empty"
+        style = "empty" if node.option?("empty")
+        list_attributes = {
+          style: style,
+          hangIndent: node.attr("hang-indent"),
+        }
+
+        xml.list **attr_code(list_attributes) do |xml_list|
+          node.items.each do |item|
+            t_attributes = {
+              anchor: nil,
+            }
+
+            xml_list.t **attr_code(t_attributes) do |xml_t|
+              xml_t << item.text
+              xml_t << para_to_vspace(item.content) if item.blocks?
+            end
+          end
+        end
+      end
+
+      def olist_naked(node, xml)
+        style = OLIST_TYPES[node.style.to_sym]
+        style = "empty" if node.attr("style") == "empty"
+        style = "format #{node.attr('format')}" unless node.attr("format").nil?
+        list_attributes = {
+          hangIndent: node.attr("hang-indent"),
+          counter: node.attr("counter"),
+          style: style,
+        }
+
+        xml.list **attr_code(list_attributes) do |xml_list|
+          node.items.each do |item|
+            t_attributes = {
+              anchor: item.id,
+            }
+
+            xml_list.t **attr_code(t_attributes) do |xml_t|
+              xml_t << item.text
+              xml_t << para_to_vspace(item.content) if item.blocks?
+            end
+          end
+        end
+      end
+
+      def dlist_naked(node, xml)
+        style = "hanging"
+        style = "empty" if node.attr("style") == "empty"
+        list_attributes = {
+          hangIndent: node.attr("hang-indent"),
+          style: style,
+        }
+
+        xml.list **attr_code(list_attributes) do |xml_list|
+          node.items.each do |terms, dd|
+            # all but last term have empty dd
+            terms.each_with_index do |term, idx|
+              t_attributes = {
+                hangText: term.text,
+              }
+
+              if idx < terms.size - 1
+                xml_list.t **attr_code(t_attributes)
+              else
+                xml_list.t **attr_code(t_attributes) do |xml_t|
+                  if !dd.nil?
+                    if dd.blocks?
+                      xml_t << dd.text if dd.text?
+                      # v2 does not support multi paragraph list items;
+                      # vspace is used to emulate them
+                      xml_t << para_to_vspace(dd.content)
+                    else
+                      xml_t << dd.text
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end