asciidoctor-rfc 0.1.0 → 0.2.0

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

@@ -0,0 +1,358 @@
+module Asciidoctor
+  module RFC::V3
+    module Base
+      # Syntax:
+      #   =Title
+      #   Author
+      #   :ipr
+      #   :obsoletes
+      #   :updates
+      #   :submissionType
+      #   :indexInclude
+      #   :iprExtract
+      #   :sortRefs
+      #   :symRefs
+      #   :tocInclude
+      #   :tocDepth
+      #
+      #   ABSTRACT
+      #
+      #   NOTEs
+      #
+      #   ==first title
+      #   CONTENT
+      #
+      #   [bibliography] # start of back matter
+      #   == Bibliography
+      #
+      #   [appendix] # start of back matter if not already started
+      #   == Appendix
+      def document(node)
+        $seen_back_matter = false
+        $seen_abstract = false
+        # If this is present, then BCP14 keywords in boldface are not assumed to be <bcp14> tags. By default they are.
+        $bcp_bold = !(node.attr? "no-rfc-bold-bcp14")
+        $smart_quotes = (node.attr("smart-quotes") != "false")
+        result = []
+        result << '<?xml version="1.0" encoding="UTF-8"?>'
+
+        t = Time.now.getutc
+        preptime = sprintf(
+          "%04d-%02d-%02dT%02d:%02d:%02dZ",
+          t.year, t.month, t.day, t.hour, t.min, t.sec
+        )
+
+        rfc_attributes = {
+          ipr:            node.attr("ipr"),
+          obsoletes:      node.attr("obsoletes"),
+          updates:        node.attr("updates"),
+          indexInclude:   node.attr("index-include"),
+          iprExtract:     node.attr("ipr-extract"),
+          sortRefs:       node.attr("sort-refs"),
+          symRefs:        node.attr("sym-refs"),
+          tocInclude:     node.attr("toc-include"),
+          tocDepth:       node.attr("toc-depth"),
+          submissionType: node.attr("submission-type") || "IETF",
+          'xml:lang':     node.attr("xml-lang"),
+          prepTime:       preptime,
+          version:        "3",
+        }
+
+        rfc_open = noko { |xml| xml.rfc **attr_code(rfc_attributes) }.join.gsub(/\/>$/, ">")
+        result << rfc_open
+
+        result << (link node)
+
+        result << noko { |xml| front node, xml }
+        result.last.last.gsub! /<\/front>$/, "" # FIXME: this is a hack!
+        result << "</front><middle1>"
+
+        result << node.content if node.blocks?
+        result << ($seen_back_matter ? "</back>" : "</middle>")
+        result << "</rfc>"
+
+        # <middle> needs to move after preamble
+        result = result.flatten
+        result = if result.any? { |e| e =~ /<\/front><middle>/ } && result.any? { |e| e =~ /<\/front><middle1>/ }
+                   result.reject { |e| e =~ /<\/front><middle1>/ }
+                 else
+                   result.map { |e| e =~ /<\/front><middle1>/ ? "</front><middle>" : e }
+                 end
+        ret = result * "\n"
+        ret = set_pis(node, Nokogiri::XML(ret)).to_xml
+        ret = cleanup ret
+        Validate::validate(ret)
+        ret
+      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: node.attr("sym-refs"),
+
+          # sort the reference entries alphabetically
+          sortrefs: node.attr("sort-refs"),
+
+          # 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",
+        }
+
+        doc.create_internal_subset("rfc", nil, "rfc2629.dtd")
+        rfc_pis.each_pair do |k, v|
+          pi = Nokogiri::XML::ProcessingInstruction.new(doc,
+                                                        "rfc",
+                                                        "#{k}=\"#{v}\"")
+          doc.root.add_previous_sibling(pi)
+        end
+
+        doc
+      end
+
+      # Syntax:
+      #   = Title
+      #   Author
+      #   :link href,href rel
+      def link(node)
+        result = []
+        result << noko do |xml|
+          links = (node.attr("link") || "").split(/,/)
+          links.each do |link|
+            matched = /^(?<href>\S+)\s+(?<rel>\S+)$/.match link
+            link_attributes = {
+              href: matched.nil? ? link : matched[:href],
+              rel: matched.nil? ? nil : matched[:rel],
+            }
+            xml.link **attr_code(link_attributes)
+          end
+        end
+        result
+      end
+
+      def inline_break(node)
+        # <br> is only defined within tables
+        noko do |xml|
+          xml << node.text
+          xml.br if node.parent.context == :cell
+        end.join
+      end
+
+      def inline_quoted(node)
+        noko do |xml|
+          case node.type
+          when :emphasis then xml.em node.text
+          when :strong
+            if $bcp_bold && node.text =~ /^(MUST|MUST NOT|REQUIRED|SHALL|SHALL NOT|SHOULD|SHOULD NOT|RECOMMENDED|MAY|OPTIONAL)$/
+              xml.bcp14 node.text
+            else
+              xml.strong node.text
+            end
+          when :monospaced then xml.tt node.text
+          when :double
+            xml << ($smart_quotes ? "“#{node.text}”" : "\"#{node.text}\"")
+          when :single
+            xml << ($smart_quotes ? "‘#{node.text}’" : "'#{node.text}'")
+          when :superscript then xml.sup node.text
+          when :subscript then xml.sub node.text
+          else
+            # [bcp14]#MUST NOT#
+            if node.role == "bcp14"
+              xml.bcp14 node.text.upcase
+            else
+              xml << node.text
+            end
+          end
+        end.join
+      end
+
+      # Syntax:
+      #   [[id]]
+      #   [keepWithNext=true,keepWithPrevious=true] (optional)
+      #   Text
+      def paragraph(node)
+        result = []
+
+        if (node.parent.context == :preamble) && !$seen_abstract
+          $seen_abstract = true
+          result << "<abstract>"
+        end
+
+        t_attributes = {
+          anchor: node.id,
+          keepWithNext: node.attr("keep-with-next"),
+          keepWithPrevious: node.attr("keep-with-previous"),
+        }
+
+        result << noko do |xml|
+          xml.t **attr_code(t_attributes) do |xml_t|
+            xml_t << node.content
+          end
+        end
+
+        result
+      end
+
+      # Syntax:
+      #   :sectnums: (toggle)
+      #   :sectnums!: (toggle)
+      #   [[id]]
+      #   [removeInRFC=true,toc=include|exclude|default] (optional)
+      #   == title
+      #   Content
+      #
+      #   [[id]]
+      #   [bibliography]
+      #   == Normative|Informative References
+      #   * [[[ref1]]] Ref [must provide references as list]
+      #   * [[[ref2]]] Ref
+      def section(node)
+        result = []
+        if node.attr("style") == "bibliography"
+          $xreftext = {}
+          $processing_reflist = true
+
+          # references_attributes = {
+          #   anchor: node.id,
+          # }.reject { |_, value| value.nil? }
+
+          # result << noko do |xml|
+          #   xml.references **references_attributes do |references_xml|
+          #     references_xml.name node.title unless node.title.nil?
+          #     node.blocks.each { |b| references_xml << reflist(b).join }
+          #   end
+          # end
+
+          anchor_attribute = node.id.nil? ? nil : " anchor=\"#{node.id}\""
+          result << "<references#{anchor_attribute}>"
+          result << "<name>#{node.title}</name>" unless node.title.nil?
+          # require that references be a :pass xml block
+          # potentially with an initial block of display reference equivalences
+          node.blocks.each do |b|
+            if b.context == :pass
+              result << reflist(b)
+            elsif b.context == :ulist
+              b.items.each do |i|
+                i.text # we only process the item for its displayreferences
+              end
+            end
+          end
+          result << "</references>"
+
+          unless $xreftext.empty?
+            result.unshift($xreftext.keys.map { |k| %(<displayreference target="#{k}" to="#{$xreftext[k]}"/>) })
+          end
+          result = result.unshift("</middle><back>") unless $seen_back_matter
+          $processing_reflist = false
+          $seen_back_matter = true
+        else
+          if node.attr("style") == "appendix"
+            result << "</middle><back>" unless $seen_back_matter
+            $seen_back_matter = true
+          end
+
+          section_attributes = {
+            anchor: node.id,
+            removeInRFC: node.attr("remove-in-rfc"),
+            toc: node.attr("toc"),
+            numbered: node.attr?("sectnums"),
+          }
+
+          result << noko do |xml|
+            xml.section **attr_code(section_attributes) do |section_xml|
+              section_xml.name { |name| name << node.title } unless node.title.nil?
+              section_xml << node.content
+            end
+          end
+        end
+        result
+      end
+
+      # Syntax:
+      #   [[id]]
+      #   .Name
+      #   [link=xxx,align=left|center|right,alt=alt_text,type]
+      #   image::filename[alt,width,height]
+      # @note ignoring width, height attributes
+      def image(node)
+        uri = node.image_uri node.attr("target")
+        artwork_attributes = {
+          align: node.attr("align"),
+          alt: node.alt,
+          anchor: node.id,
+          height: node.attr("height"),
+          name: node.title,
+          src: uri,
+          type: (uri =~ /\.svg$/ ? "svg" : "binary-art"),
+          width: node.attr("width"),
+        }
+
+        noko do |xml|
+          if node.parent.context != :example
+            xml.figure do |xml_figure|
+              xml_figure.artwork **attr_code(artwork_attributes)
+            end
+          else
+            xml.artwork **attr_code(artwork_attributes)
+          end
+        end
+      end
+
+      # clean up XML
+      def cleanup(doc)
+        xmldoc = Nokogiri::XML(doc)
+        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.each do |cref|
+          if cref.parent.name == "section"
+            prev = cref.previous_element
+            if !prev.nil? && prev.name == "t"
+              cref.parent = prev
+            else
+              t = Nokogiri::XML::Element.new("t", xmldoc)
+              cref.before(t)
+              cref.parent = t
+            end
+          end
+        end
+        unless $smart_quotes
+          xmldoc.traverse do |node|
+            if node.text?
+              node.content = node.content.tr("\u2019", "'")
+              node.content = node.content.gsub(/\&#8217;/, "'")
+              node.content = node.content.gsub(/\&#x2019;/, "'")
+            elsif node.element?
+              node.attributes.each do |k, v|
+                node.set_attribute(k, v.content.tr("\u2019", "'"))
+                node.set_attribute(k, v.content.gsub(/\&#8217;/, "'"))
+                node.set_attribute(k, v.content.gsub(/\&#x2019;/, "'"))
+              end
+            end
+          end
+        end
+
+        xmldoc.to_xml(encoding: "US-ASCII")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,203 @@
+module Asciidoctor
+  module RFC::V3
+    module Blocks
+      # Syntax:
+      # [discrete]
+      # == Section
+      def floating_title(node)
+        noko do |xml|
+          xml.t { |xml_t| xml_t.strong node.title }
+        end
+      end
+
+      # Syntax:
+      #   [[id]]
+      #   .name
+      #   [align=left|center|right,alt=alt_text] (optional)
+      #   ....
+      #     literal
+      #   ....
+      def literal(node)
+        artwork_attributes = {
+          anchor: node.id,
+          align: node.attr("align"),
+          type: "ascii-art",
+          name: node.title,
+          alt: node.attr("alt"),
+        }
+
+        # NOTE: html escaping is performed by Nokogiri
+        artwork_content = node.lines.join("\n")
+
+        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
+      end
+
+      # Syntax:
+      #   [[id]]
+      #   [quote, attribution, citation info] # citation info limited to URL
+      #   Text
+      def quote(node)
+        cite_value = node.attr("citetitle")
+        cite_value = nil unless cite_value.to_s =~ URI::DEFAULT_PARSER.make_regexp
+
+        blockquote_attributes = {
+          anchor: node.id,
+          quotedFrom: node.attr("attribution"),
+          cite: cite_value,
+        }
+
+        noko do |xml|
+          xml.blockquote **attr_code(blockquote_attributes) do |xml_blockquote|
+            xml_blockquote << node.content
+          end
+        end
+      end
+
+      # realise as quote() ; <br/> in v3 does not have the applicability of <vspace/>,
+      # it is restricted to tables
+      def verse(node)
+        quote(node)
+      end
+
+      # Syntax:
+      #   = Title
+      #   Author
+      #   :HEADER
+      #
+      #   ABSTRACT
+      #
+      #   NOTE: note
+      #
+      #   [NOTE]
+      #   .Title (in preamble)
+      #   ====
+      #     Content
+      #   ====
+      #
+      #     [NOTE,removeInRFC=true] (in preamble)
+      #     [NOTE,display=true|false,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 = {
+            removeInRFC: node.attr("remove-in-rfc"),
+          }
+
+          result << noko do |xml|
+            xml.note **attr_code(note_attributes) do |xml_note|
+              xml_note.name node.title unless node.title.nil?
+              xml_note << [paragraph1(node)].flatten.join("\n")
+            end
+          end
+        else
+          cref_attributes = {
+            anchor: node.id,
+            display: node.attr("display"),
+            source: node.attr("source"),
+          }
+
+          cref_contents = node.blocks? ? flatten(node) : node.content
+          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|
+            xml.cref **attr_code(cref_attributes) do |xml_cref|
+              xml_cref << cref_contents
+            end
+          end
+        end
+        result
+      end
+
+      # Syntax:
+      #   [[id]]
+      #   ****
+      #   Sidebar
+      #   ****
+      def sidebar(node)
+        noko do |xml|
+          xml.aside anchor: node.id do |xml_aside|
+            xml_aside << node.content
+          end
+        end
+      end
+
+      # Syntax:
+      #   .Title
+      #   ====
+      #   Example
+      #   ====
+      def example(node)
+        node.blocks.each do |b|
+          unless %i{listing image literal}.include? b.context
+            warn "asciidoctor: WARNING: examples (figures) should only contain listings (sourcecode), images (artwork), or literal (artwork):\n#{b.lines}"
+          end
+        end
+
+        figure_attributes = {
+          anchor: node.id,
+        }
+
+        noko do |xml|
+          xml.figure **attr_code(figure_attributes) do |xml_figure|
+            xml_figure.name node.title if node.title?
+            # TODO iref
+            xml_figure << node.content
+          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 = {
+          anchor: node.id,
+          align: nil,
+          alt: nil,
+          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.sourcecode sourcecode_content, **attr_code(sourcecode_attributes)
+            end
+          else
+            xml.sourcecode sourcecode_content, **attr_code(sourcecode_attributes)
+          end
+        end
+      end
+    end
+  end
+end