asciidoctor 2.0.9 → 2.0.14

data/lib/asciidoctor/converter/docbook5.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 module Asciidoctor
 # A built-in {Converter} implementation that generates DocBook 5 output. The output is inspired by the output produced
-# by the docbook45 backend from AsciiDoc Python, except it has been migrated to the DocBook 5 specification.
+# by the docbook45 backend from AsciiDoc.py, except it has been migrated to the DocBook 5 specification.
 class Converter::DocBook5Converter < Converter::Base
   register_for 'docbook5'
 
@@ -371,9 +371,7 @@ class Converter::DocBook5Converter < Converter::Base
     has_body = false
     result = []
     pgwide_attribute = (node.option? 'pgwide') ? ' pgwide="1"' : ''
-    if (frame = node.attr 'frame', 'all', 'table-frame') == 'ends'
-      frame = 'topbot'
-    end
+    frame = 'topbot' if (frame = node.attr 'frame', 'all', 'table-frame') == 'ends'
     grid = node.attr 'grid', nil, 'table-grid'
     result << %(<#{tag_name = node.title? ? 'table' : 'informaltable'}#{common_attributes node.id, node.role, node.reftext}#{pgwide_attribute} frame="#{frame}" rowsep="#{['none', 'cols'].include?(grid) ? 0 : 1}" colsep="#{['none', 'rows'].include?(grid) ? 0 : 1}"#{(node.attr? 'orientation', 'landscape', 'table-orientation') ? ' orient="land"' : ''}>)
     if (node.option? 'unbreakable')
@@ -401,12 +399,10 @@ class Converter::DocBook5Converter < Converter::Base
       rows.each do |row|
         result << '<row>'
         row.each do |cell|
-          halign_attribute = (cell.attr? 'halign') ? %( align="#{cell.attr 'halign'}") : ''
-          valign_attribute = (cell.attr? 'valign') ? %( valign="#{cell.attr 'valign'}") : ''
           colspan_attribute = cell.colspan ? %( namest="col_#{colnum = cell.column.attr 'colnumber'}" nameend="col_#{colnum + cell.colspan - 1}") : ''
           rowspan_attribute = cell.rowspan ? %( morerows="#{cell.rowspan - 1}") : ''
           # NOTE <entry> may not have whitespace (e.g., line breaks) as a direct descendant according to DocBook rules
-          entry_start = %(<entry#{halign_attribute}#{valign_attribute}#{colspan_attribute}#{rowspan_attribute}>)
+          entry_start = %(<entry align="#{cell.attr 'halign'}" valign="#{cell.attr 'valign'}"#{colspan_attribute}#{rowspan_attribute}>)
           if tsec == :head
             cell_content = cell.text
           else
@@ -487,7 +483,7 @@ class Converter::DocBook5Converter < Converter::Base
     when :link
       %(<link xl:href="#{node.target}">#{node.text}</link>)
     when :bibref
-      %(<anchor#{common_attributes node.id, nil, "[#{node.reftext || node.id}]"}/>#{text})
+      %(<anchor#{common_attributes node.id, nil, (text = "[#{node.reftext || node.id}]")}/>#{text})
     else
       logger.warn %(unknown anchor type: #{node.type.inspect})
       nil
@@ -517,7 +513,7 @@ class Converter::DocBook5Converter < Converter::Base
   def convert_inline_image node
     width_attribute = (node.attr? 'width') ? %( contentwidth="#{node.attr 'width'}") : ''
     depth_attribute = (node.attr? 'height') ? %( contentdepth="#{node.attr 'height'}") : ''
-    %(<inlinemediaobject>
+    %(<inlinemediaobject#{common_attributes nil, node.role}>
 <imageobject>
 <imagedata fileref="#{node.type == 'icon' ? (node.icon_uri node.target) : (node.image_uri node.target)}"#{width_attribute}#{depth_attribute}/>
 </imageobject>

data/lib/asciidoctor/converter/html5.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 module Asciidoctor
 # A built-in {Converter} implementation that generates HTML 5 output
-# consistent with the html5 backend from AsciiDoc Python.
+# consistent with the html5 backend from AsciiDoc.py.
 class Converter::Html5Converter < Converter::Base
   register_for 'html5'
 
@@ -21,15 +21,15 @@ class Converter::Html5Converter < Converter::Base
     #latexmath:  INLINE_MATH_DELIMITERS[:latexmath] + [false],
   }).default = ['', '']
 
-  DropAnchorRx = /<(?:a[^>+]+|\/a)>/
+  DropAnchorRx = /<(?:a\b[^>]*|\/a)>/
   StemBreakRx = / *\\\n(?:\\?\n)*|\n\n+/
   if RUBY_ENGINE == 'opal'
     # NOTE In JavaScript, ^ matches the start of the string when the m flag is not set
-    SvgPreambleRx = /^#{CC_ALL}*?(?=<svg\b)/
-    SvgStartTagRx = /^<svg[^>]*>/
+    SvgPreambleRx = /^#{CC_ALL}*?(?=<svg[\s>])/
+    SvgStartTagRx = /^<svg(?:\s[^>]*)?>/
   else
-    SvgPreambleRx = /\A.*?(?=<svg\b)/m
-    SvgStartTagRx = /\A<svg[^>]*>/
+    SvgPreambleRx = /\A.*?(?=<svg[\s>])/m
+    SvgStartTagRx = /\A<svg(?:\s[^>]*)?>/
   end
   DimensionAttributeRx = /\s(?:width|height|style)=(["'])#{CC_ANY}*?\1/
 
@@ -96,6 +96,7 @@ class Converter::Html5Converter < Converter::Base
     end
     cdn_base_url = %(#{asset_uri_scheme}//cdnjs.cloudflare.com/ajax/libs)
     linkcss = node.attr? 'linkcss'
+    max_width_attr = (node.attr? 'max-width') ? %( style="max-width: #{node.attr 'max-width'};") : ''
     result = ['<!DOCTYPE html>']
     lang_attribute = (node.attr? 'nolang') ? '' : %( lang="#{node.attr 'lang', 'en'}")
     result << %(<html#{@xml_mode ? ' xmlns="http://www.w3.org/1999/xhtml"' : ''}#{lang_attribute}>)
@@ -138,7 +139,7 @@ class Converter::Html5Converter < Converter::Base
         result << %(<link rel="stylesheet" href="#{node.normalize_web_path((node.attr 'stylesheet'), (node.attr 'stylesdir', ''))}"#{slash}>)
       else
         result << %(<style>
-#{node.read_asset node.normalize_system_path((node.attr 'stylesheet'), (node.attr 'stylesdir', '')), warn_on_failure: true, label: 'stylesheet'}
+#{node.read_contents (node.attr 'stylesheet'), start: (node.attr 'stylesdir'), warn_on_failure: true, label: 'stylesheet'}
 </style>)
       end
     end
@@ -152,8 +153,8 @@ class Converter::Html5Converter < Converter::Base
       end
     end
 
-    if (syntax_hl = node.syntax_highlighter) && (syntax_hl.docinfo? :head)
-      result << (syntax_hl.docinfo :head, node, linkcss: linkcss)
+    if (syntax_hl = node.syntax_highlighter)
+      result << (syntax_hl_docinfo_head_idx = result.size)
     end
 
     unless (docinfo_content = node.docinfo).empty?
@@ -161,29 +162,27 @@ class Converter::Html5Converter < Converter::Base
     end
 
     result << '</head>'
-    body_attrs = node.id ? [%(id="#{node.id}")] : []
+    id_attr = node.id ? %( id="#{node.id}") : ''
     if (sectioned = node.sections?) && (node.attr? 'toc-class') && (node.attr? 'toc') && (node.attr? 'toc-placement', 'auto')
       classes = [node.doctype, (node.attr 'toc-class'), %(toc-#{node.attr 'toc-position', 'header'})]
     else
       classes = [node.doctype]
     end
     classes << node.role if node.role?
-    body_attrs << %(class="#{classes.join ' '}")
-    body_attrs << %(style="max-width: #{node.attr 'max-width'};") if node.attr? 'max-width'
-    result << %(<body #{body_attrs.join ' '}>)
+    result << %(<body#{id_attr} class="#{classes.join ' '}">)
 
     unless (docinfo_content = node.docinfo :header).empty?
       result << docinfo_content
     end
 
     unless node.noheader
-      result << '<div id="header">'
+      result << %(<div id="header"#{max_width_attr}>)
       if node.doctype == 'manpage'
         result << %(<h1>#{node.doctitle} Manual Page</h1>)
         if sectioned && (node.attr? 'toc') && (node.attr? 'toc-placement', 'auto')
           result << %(<div id="toc" class="#{node.attr 'toc-class', 'toc'}">
 <div id="toctitle">#{node.attr 'toc-title'}</div>
-#{convert_outline node}
+#{node.converter.convert node, 'outline'}
 </div>)
         end
         result << (generate_manname_section node) if node.attr? 'manpurpose'
@@ -216,19 +215,19 @@ class Converter::Html5Converter < Converter::Base
         if sectioned && (node.attr? 'toc') && (node.attr? 'toc-placement', 'auto')
           result << %(<div id="toc" class="#{node.attr 'toc-class', 'toc'}">
 <div id="toctitle">#{node.attr 'toc-title'}</div>
-#{convert_outline node}
+#{node.converter.convert node, 'outline'}
 </div>)
         end
       end
       result << '</div>'
     end
 
-    result << %(<div id="content">
+    result << %(<div id="content"#{max_width_attr}>
 #{node.content}
 </div>)
 
     if node.footnotes? && !(node.attr? 'nofootnotes')
-      result << %(<div id="footnotes">
+      result << %(<div id="footnotes"#{max_width_attr}>
 <hr#{slash}>)
       node.footnotes.each do |footnote|
         result << %(<div class="footnote" id="_footnotedef_#{footnote.index}">
@@ -239,7 +238,7 @@ class Converter::Html5Converter < Converter::Base
     end
 
     unless node.nofooter
-      result << '<div id="footer">'
+      result << %(<div id="footer"#{max_width_attr}>)
       result << '<div id="footer-text">'
       result << %(#{node.attr 'version-label'} #{node.attr 'revnumber'}#{br}) if node.attr? 'revnumber'
       result << %(#{node.attr 'last-update-label'} #{node.attr 'docdatetime'}) if (node.attr? 'last-update-label') && !(node.attr? 'reproducible')
@@ -250,8 +249,15 @@ class Converter::Html5Converter < Converter::Base
     # JavaScript (and auxiliary stylesheets) loaded at the end of body for performance reasons
     # See http://www.html5rocks.com/en/tutorials/speed/script-loading/
 
-    if syntax_hl && (syntax_hl.docinfo? :footer)
-      result << (syntax_hl.docinfo :footer, node, cdn_base_url: cdn_base_url, linkcss: linkcss, self_closing_tag_slash: slash)
+    if syntax_hl
+      if syntax_hl.docinfo? :head
+        result[syntax_hl_docinfo_head_idx] = syntax_hl.docinfo :head, node, cdn_base_url: cdn_base_url, linkcss: linkcss, self_closing_tag_slash: slash
+      else
+        result.delete_at syntax_hl_docinfo_head_idx
+      end
+      if syntax_hl.docinfo? :footer
+        result << (syntax_hl.docinfo :footer, node, cdn_base_url: cdn_base_url, linkcss: linkcss, self_closing_tag_slash: slash)
+      end
     end
 
     if node.attr? 'stem'
@@ -275,7 +281,7 @@ MathJax.Hub.Config({
 })
 MathJax.Hub.Register.StartupHook("AsciiMath Jax Ready", function () {
   MathJax.InputJax.AsciiMath.postfilterHooks.Add(function (data, node) {
-    if ((node = data.script.parentNode) && (node = node.parentNode) && node.classList.contains('stemblock')) {
+    if ((node = data.script.parentNode) && (node = node.parentNode) && node.classList.contains("stemblock")) {
       data.math.root.display = "block"
     }
     return data
@@ -311,7 +317,7 @@ MathJax.Hub.Register.StartupHook("AsciiMath Jax Ready", function () {
     if node.sections? && (node.attr? 'toc') && (toc_p = node.attr 'toc-placement') != 'macro' && toc_p != 'preamble'
       result << %(<div id="toc" class="toc">
 <div id="toctitle">#{node.attr 'toc-title'}</div>
-#{convert_outline node}
+#{node.converter.convert node, 'outline'}
 </div>)
     end
 
@@ -628,9 +634,7 @@ Your browser does not support the audio tag.
       end
     end
     img ||= %(<img src="#{node.image_uri target}" alt="#{encode_attribute_value node.alt}"#{width_attr}#{height_attr}#{@void_element_slash}>)
-    if node.attr? 'link'
-      img = %(<a class="image" href="#{node.attr 'link'}"#{(append_link_constraint_attrs node).join}>#{img}</a>)
-    end
+    img = %(<a class="image" href="#{node.attr 'link'}"#{(append_link_constraint_attrs node).join}>#{img}</a>) if node.attr? 'link'
     id_attr = node.id ? %( id="#{node.id}") : ''
     classes = ['imageblock']
     classes << (node.attr 'float') if node.attr? 'float'
@@ -689,8 +693,8 @@ Your browser does not support the audio tag.
     open, close = BLOCK_MATH_DELIMITERS[style = node.style.to_sym]
     if (equation = node.content)
       if style == :asciimath && (equation.include? LF)
-        br = %(<br#{@void_element_slash}>#{LF})
-        equation = equation.gsub(StemBreakRx) { %(#{close}#{br * ($&.count LF)}#{open}) }
+        br = %(#{LF}<br#{@void_element_slash}>)
+        equation = equation.gsub(StemBreakRx) { %(#{close}#{br * (($&.count LF) - 1)}#{LF}#{open}) }
       end
       unless (equation.start_with? open) && (equation.end_with? close)
         equation = %(#{open}#{equation}#{close})
@@ -796,7 +800,7 @@ Your browser does not support the audio tag.
       toc = %(
 <div id="toc" class="#{doc.attr 'toc-class', 'toc'}">
 <div id="toctitle">#{doc.attr 'toc-title'}</div>
-#{convert_outline doc}
+#{doc.converter.convert doc, 'outline'}
 </div>)
     else
       toc = ''
@@ -848,7 +852,8 @@ Your browser does not support the audio tag.
   def convert_table node
     result = []
     id_attribute = node.id ? %( id="#{node.id}") : ''
-    classes = ['tableblock', %(frame-#{node.attr 'frame', 'all', 'table-frame'}), %(grid-#{node.attr 'grid', 'all', 'table-grid'})]
+    frame = 'ends' if (frame = node.attr 'frame', 'all', 'table-frame') == 'topbot'
+    classes = ['tableblock', %(frame-#{frame}), %(grid-#{node.attr 'grid', 'all', 'table-grid'})]
     if (stripes = node.attr 'stripes', nil, 'table-stripes')
       classes << %(stripes-#{stripes})
     end
@@ -934,7 +939,7 @@ Your browser does not support the audio tag.
 
     %(<div#{id_attr} class="#{role}">
 <div#{title_id_attr} class="title">#{title}</div>
-#{convert_outline doc, toclevels: levels}
+#{doc.converter.convert doc, 'outline', toclevels: levels}
 </div>)
   end
 
@@ -1089,7 +1094,7 @@ Your browser does not support the audio tag.
       time_anchor = (start_t || end_t) ? %(#t=#{start_t || ''}#{end_t ? ",#{end_t}" : ''}) : ''
       %(<div#{id_attribute}#{class_attribute}>#{title_element}
 <div class="content">
-<video src="#{node.media_uri(node.attr 'target')}#{time_anchor}"#{width_attribute}#{height_attribute}#{poster_attribute}#{(node.option? 'autoplay') ? (append_boolean_attribute 'autoplay', xml) : ''}#{(node.option? 'nocontrols') ? '' : (append_boolean_attribute 'controls', xml)}#{(node.option? 'loop') ? (append_boolean_attribute 'loop', xml) : ''}#{preload_attribute}>
+<video src="#{node.media_uri(node.attr 'target')}#{time_anchor}"#{width_attribute}#{height_attribute}#{poster_attribute}#{(node.option? 'autoplay') ? (append_boolean_attribute 'autoplay', xml) : ''}#{(node.option? 'muted') ? (append_boolean_attribute 'muted', xml) : ''}#{(node.option? 'nocontrols') ? '' : (append_boolean_attribute 'controls', xml)}#{(node.option? 'loop') ? (append_boolean_attribute 'loop', xml) : ''}#{preload_attribute}>
 Your browser does not support the video tag.
 </video>
 </div>
@@ -1107,8 +1112,13 @@ Your browser does not support the video tag.
         attrs = node.role ? %( class="#{node.role}") : ''
         unless (text = node.text)
           refid = node.attributes['refid']
-          if AbstractNode === (ref = (@refs ||= node.document.catalog[:refs])[refid])
-            text = (ref.xreftext node.attr('xrefstyle', nil, true)) || %([#{refid}])
+          if AbstractNode === (ref = (@refs ||= node.document.catalog[:refs])[refid]) && (@resolving_xref ||= (outer = true)) && outer
+            if !(text = ref.xreftext node.attr 'xrefstyle', nil, true)
+              text = %([#{refid}])
+            elsif text.include? '<a'
+              text = text.gsub DropAnchorRx, ''
+            end
+            @resolving_xref = nil
           else
             text = %([#{refid}])
           end
@@ -1144,8 +1154,10 @@ Your browser does not support the video tag.
     elsif node.document.attr? 'icons'
       src = node.icon_uri("callouts/#{node.text}")
       %(<img src="#{src}" alt="#{node.text}"#{@void_element_slash}>)
+    elsif ::Array === (guard = node.attributes['guard'])
+      %(&lt;!--<b class="conum">(#{node.text})</b>--&gt;)
     else
-      %(#{node.attributes['guard']}<b class="conum">(#{node.text})</b>)
+      %(#{guard}<b class="conum">(#{node.text})</b>)
     end
   end
 
@@ -1186,9 +1198,7 @@ Your browser does not support the video tag.
       end
       img ||= %(<img src="#{type == 'icon' ? (node.icon_uri target) : (node.image_uri target)}" alt="#{encode_attribute_value node.alt}"#{attrs}#{@void_element_slash}>)
     end
-    if node.attr? 'link'
-      img = %(<a class="image" href="#{node.attr 'link'}"#{(append_link_constraint_attrs node).join}>#{img}</a>)
-    end
+    img = %(<a class="image" href="#{node.attr 'link'}"#{(append_link_constraint_attrs node).join}>#{img}</a>) if node.attr? 'link'
     if (role = node.role)
       if node.attr? 'float'
         class_attr_val = %(#{type} #{node.attr 'float'} #{role})
@@ -1252,16 +1262,19 @@ Your browser does not support the video tag.
 
   # NOTE expose read_svg_contents for Bespoke converter
   def read_svg_contents node, target
-    if (svg = node.read_contents target, start: (node.document.attr 'imagesdir'), normalize: true, label: 'SVG')
+    if (svg = node.read_contents target, start: (node.document.attr 'imagesdir'), normalize: true, label: 'SVG', warn_if_empty: true)
+      return if svg.empty?
       svg = svg.sub SvgPreambleRx, '' unless svg.start_with? '<svg'
-      old_start_tag = new_start_tag = nil
+      old_start_tag = new_start_tag = start_tag_match = nil
       # NOTE width, height and style attributes are removed if either width or height is specified
       ['width', 'height'].each do |dim|
-        if node.attr? dim
-          new_start_tag = (old_start_tag = (svg.match SvgStartTagRx)[0]).gsub DimensionAttributeRx, '' unless new_start_tag
-          # QUESTION should we add px since it's already the default?
-          new_start_tag = %(#{new_start_tag.chop} #{dim}="#{node.attr dim}px">)
+        next unless node.attr? dim
+        unless new_start_tag
+          next if (start_tag_match ||= (svg.match SvgStartTagRx) || :no_match) == :no_match
+          new_start_tag = (old_start_tag = start_tag_match[0]).gsub DimensionAttributeRx, ''
         end
+        # NOTE a unitless value in HTML is assumed to be px, so we can pass the value straight through
+        new_start_tag = %(#{new_start_tag.chop} #{dim}="#{node.attr dim}">)
       end
       svg = %(#{new_start_tag}#{svg[old_start_tag.length..-1]}) if new_start_tag
     end
@@ -1297,7 +1310,7 @@ Your browser does not support the video tag.
     manname_id_attr = (manname_id = node.attr 'manname-id') ? %( id="#{manname_id}") : ''
     %(<h2#{manname_id_attr}>#{manname_title}</h2>
 <div class="sectionbody">
-<p>#{node.attr 'manname'} - #{node.attr 'manpurpose'}</p>
+<p>#{(node.attr 'mannames').join ', '} - #{node.attr 'manpurpose'}</p>
 </div>)
   end
 

data/lib/asciidoctor/converter/manpage.rb

@@ -2,8 +2,12 @@
 module Asciidoctor
 # A built-in {Converter} implementation that generates the man page (troff) format.
 #
-# The output follows the groff man page definition while also trying to be
-# consistent with the output produced by the a2x tool from AsciiDoc Python.
+# The output of this converter adheres to the man definition as defined by
+# groff and uses the manpage output of the DocBook toolchain as a foundation.
+# That means if you've previously been generating man pages using the a2x tool
+# from AsciiDoc.py, you should be able to achieve a very similar result
+# using this converter. Though you'll also get to enjoy some notable
+# enhancements that have been added since, such as the customizable linkstyle.
 #
 # See http://www.gnu.org/software/groff/manual/html_node/Man-usage.html#Man-usage
 class Converter::ManPageConverter < Converter::Base
@@ -15,13 +19,16 @@ class Converter::ManPageConverter < Converter::Base
   ESC_BS = %(#{ESC}\\) # escaped backslash (indicates troff formatting sequence)
   ESC_FS = %(#{ESC}.)  # escaped full stop (indicates troff macro)
 
-  LiteralBackslashRx = /(?:\A|[^#{ESC}])\\/
+  LiteralBackslashRx = /\A\\|(#{ESC})?\\/
   LeadingPeriodRx = /^\./
   EscapedMacroRx = /^(?:#{ESC}\\c\n)?#{ESC}\.((?:URL|MTO) "#{CC_ANY}*?" "#{CC_ANY}*?" )( |[^\s]*)(#{CC_ANY}*?)(?: *#{ESC}\\c)?$/
-  MockBoundaryRx = /<\/?BOUNDARY>/
+  MalformedEscapedMacroRx = /(#{ESC}\\c) (#{ESC}\.(?:URL|MTO) )/
+  MockMacroRx = /<\/?(#{ESC}\\[^>]+)>/
   EmDashCharRefRx = /&#8212;(?:&#8203;)?/
   EllipsisCharRefRx = /&#8230;(?:&#8203;)?/
   WrappedIndentRx = /#{CG_BLANK}*#{LF}#{CG_BLANK}*/
+  XMLMarkupRx = /&#?[a-z\d]+;|</
+  PCDATAFilterRx = /(&#?[a-z\d]+;|<[^>]+>)|([^&<]+)/
 
   def initialize backend, opts = {}
     @backend = backend
@@ -91,17 +98,14 @@ class Converter::ManPageConverter < Converter::Base
       if node.attr? 'manpurpose'
         mannames = node.attr 'mannames', [manname]
         result << %(.SH "#{(node.attr 'manname-title', 'NAME').upcase}"
-#{mannames.map {|n| manify n }.join ', '} \\- #{manify node.attr('manpurpose'), whitespace: :normalize})
+#{mannames.map {|n| (manify n).gsub '\-', '-' }.join ', '} \\- #{manify node.attr('manpurpose'), whitespace: :normalize})
       end
     end
 
     result << node.content
 
     # QUESTION should NOTES come after AUTHOR(S)?
-    if node.footnotes? && !(node.attr? 'nofootnotes')
-      result << '.SH "NOTES"'
-      result.concat(node.footnotes.map {|fn| %(#{fn.index}. #{fn.text}) })
-    end
+    append_footnotes result, node
 
     unless (authors = node.authors).empty?
       if authors.size > 1
@@ -124,10 +128,7 @@ class Converter::ManPageConverter < Converter::Base
   def convert_embedded node
     result = [node.content]
 
-    if node.footnotes? && !(node.attr? 'nofootnotes')
-      result << '.SH "NOTES"'
-      result.concat(node.footnotes.map {|fn| %(#{fn.index}. #{fn.text}) })
-    end
+    append_footnotes result, node
 
     # QUESTION should we add an AUTHOR(S) section?
 
@@ -142,7 +143,7 @@ class Converter::ManPageConverter < Converter::Base
       stitle = node.captioned_title
     else
       macro = 'SH'
-      stitle = node.title.upcase
+      stitle = uppercase_pcdata node.title
     end
     result << %(.#{macro} "#{manify stitle}"
 #{node.content})
@@ -247,7 +248,9 @@ r lw(\n(.lu*75u/100u).'
     result << %(.sp
 .if n .RS 4
 .nf
+.fam C
 #{manify node.content, whitespace: :preserve}
+.fam
 .fi
 .if n .RE)
     result.join LF
@@ -261,7 +264,9 @@ r lw(\n(.lu*75u/100u).'
     result << %(.sp
 .if n .RS 4
 .nf
+.fam C
 #{manify node.content, whitespace: :preserve}
+.fam
 .fi
 .if n .RE)
     result.join LF
@@ -284,15 +289,16 @@ r lw(\n(.lu*75u/100u).'
 .B #{manify node.title}
 .br) if node.title?
 
+    start = (node.attr 'start', 1).to_i
     node.items.each_with_index do |item, idx|
       result << %(.sp
 .RS 4
 .ie n \\{\\
-\\h'-04' #{idx + 1}.\\h'+01'\\c
+\\h'-04' #{numeral = idx + start}.\\h'+01'\\c
 .\\}
 .el \\{\\
 .  sp -1
-.  IP " #{idx + 1}." 4.2
+.  IP " #{numeral}." 4.2
 .\\}
 #{manify item.text, whitespace: :normalize})
       result << item.content if item.blocks?
@@ -310,8 +316,9 @@ r lw(\n(.lu*75u/100u).'
     end
   end
 
-  # TODO use Page Control https://www.gnu.org/software/groff/manual/html_node/Page-Control.html#Page-Control
-  alias convert_page_break skip
+  def convert_page_break node
+    '.bp'
+  end
 
   def convert_paragraph node
     if node.title?
@@ -526,12 +533,13 @@ allbox tab(:);'
     result.join LF
   end
 
-  # FIXME git uses [verse] for the synopsis; detect this special case
   def convert_verse node
     result = []
-    result << (node.title? ? %(.sp
+    if node.title?
+      result << %(.sp
 .B #{manify node.title}
-.br) : '.sp')
+.br)
+    end
     attribution_line = (node.attr? 'citetitle') ? %(#{node.attr 'citetitle'} ) : nil
     attribution_line = (node.attr? 'attribution') ? %[#{attribution_line}\\(em #{node.attr 'attribution'}] : nil
     result << %(.sp
@@ -580,11 +588,7 @@ allbox tab(:);'
     when :xref
       unless (text = node.text)
         refid = node.attributes['refid']
-        if AbstractNode === (ref = (@refs ||= node.document.catalog[:refs])[refid])
-          text = (ref.xreftext node.attr('xrefstyle', nil, true)) || %([#{refid}])
-        else
-          text = %([#{refid}])
-        end
+        text = %([#{refid}]) unless AbstractNode === (ref = (@refs ||= node.document.catalog[:refs])[refid]) && (@resolving_xref ||= outer = true) && outer && (text = ref.xreftext node.attr 'xrefstyle', nil, true)
       end
       text
     when :ref, :bibref
@@ -608,7 +612,6 @@ allbox tab(:);'
     %(#{ESC_BS}fB(#{node.text})#{ESC_BS}fP)
   end
 
-  # TODO supposedly groff has footnotes, but we're in search of an example
   def convert_inline_footnote node
     if (index = node.attr 'index')
       %([#{index}])
@@ -646,19 +649,19 @@ allbox tab(:);'
     end
   end
 
-  # NOTE use fake <BOUNDARY> element to prevent creating artificial word boundaries
+  # NOTE use fake XML elements to prevent creating artificial word boundaries
   def convert_inline_quoted node
     case node.type
     when :emphasis
-      %(#{ESC_BS}fI<BOUNDARY>#{node.text}</BOUNDARY>#{ESC_BS}fP)
+      %(<#{ESC_BS}fI>#{node.text}</#{ESC_BS}fP>)
     when :strong
-      %(#{ESC_BS}fB<BOUNDARY>#{node.text}</BOUNDARY>#{ESC_BS}fP)
+      %(<#{ESC_BS}fB>#{node.text}</#{ESC_BS}fP>)
     when :monospaced
-      %[#{ESC_BS}f(CR<BOUNDARY>#{node.text}</BOUNDARY>#{ESC_BS}fP]
+      %[<#{ESC_BS}f(CR>#{node.text}</#{ESC_BS}fP>]
     when :single
-      %[#{ESC_BS}(oq<BOUNDARY>#{node.text}</BOUNDARY>#{ESC_BS}(cq]
+      %[<#{ESC_BS}(oq>#{node.text}</#{ESC_BS}(cq>]
     when :double
-      %[#{ESC_BS}(lq<BOUNDARY>#{node.text}</BOUNDARY>#{ESC_BS}(rq]
+      %[<#{ESC_BS}(lq>#{node.text}</#{ESC_BS}(rq>]
     else
       node.text
     end
@@ -677,6 +680,22 @@ allbox tab(:);'
 
   private
 
+  def append_footnotes result, node
+    if node.footnotes? && !(node.attr? 'nofootnotes')
+      result << '.SH "NOTES"'
+      node.footnotes.each_with_index do |fn, idx|
+        result << %(.IP [#{fn.index}])
+        # NOTE restore newline in escaped macro that gets removed by normalize_text in substitutor
+        if (text = fn.text).include? %(#{ESC}\\c #{ESC}.)
+          text = (manify %(#{text.gsub MalformedEscapedMacroRx, %(\\1#{LF}\\2)} ), whitespace: :normalize).chomp ' '
+        else
+          text = manify text, whitespace: :normalize
+        end
+        result << text
+      end
+    end
+  end
+
   # Converts HTML entity references back to their original form, escapes
   # special man characters and strips trailing whitespace.
   #
@@ -699,10 +718,11 @@ allbox tab(:);'
       str = str.tr_s WHITESPACE, ' '
     end
     str = str.
-      gsub(LiteralBackslashRx, '\&(rs'). # literal backslash (not a troff escape sequence)
+      gsub(LiteralBackslashRx) { $1 ? $& : '\\(rs' }. # literal backslash (not a troff escape sequence)
+      gsub(EllipsisCharRefRx, '...'). # horizontal ellipsis
       gsub(LeadingPeriodRx, '\\\&.'). # leading . is used in troff for macro call or other formatting; replace with \&.
       # drop orphaned \c escape lines, unescape troff macro, quote adjacent character, isolate macro line
-      gsub(EscapedMacroRx) { (rest = $3.lstrip).empty? ? %(.#$1"#$2") : %(.#$1"#$2"#{LF}#{rest}) }.
+      gsub(EscapedMacroRx) { (rest = $3.lstrip).empty? ? %(.#$1"#$2") : %(.#$1"#{$2.rstrip}"#{LF}#{rest}) }.
       gsub('-', '\-').
       gsub('&lt;', '<').
       gsub('&gt;', '>').
@@ -717,21 +737,24 @@ allbox tab(:);'
       gsub('&#8217;', '\(cq').  # right single quotation mark
       gsub('&#8220;', '\(lq').  # left double quotation mark
       gsub('&#8221;', '\(rq').  # right double quotation mark
-      gsub(EllipsisCharRefRx, '...'). # horizontal ellipsis
       gsub('&#8592;', '\(<-').  # leftwards arrow
       gsub('&#8594;', '\(->').  # rightwards arrow
       gsub('&#8656;', '\(lA').  # leftwards double arrow
       gsub('&#8658;', '\(rA').  # rightwards double arrow
       gsub('&#8203;', '\:').    # zero width space
-      gsub('&amp;','&').        # literal ampersand (NOTE must take place after any other replacement that includes &)
+      gsub('&amp;', '&').       # literal ampersand (NOTE must take place after any other replacement that includes &)
       gsub('\'', '\(aq').       # apostrophe-quote
-      gsub(MockBoundaryRx, ''). # mock boundary
+      gsub(MockMacroRx, '\1').  # mock boundary
       gsub(ESC_BS, '\\').       # unescape troff backslash (NOTE update if more escapes are added)
       gsub(ESC_FS, '.').        # unescape full stop in troff commands (NOTE must take place after gsub(LeadingPeriodRx))
       rstrip                    # strip trailing space
     opts[:append_newline] ? %(#{str}#{LF}) : str
   end
 
+  def uppercase_pcdata string
+    (XMLMarkupRx.match? string) ? string.gsub(PCDATAFilterRx) { $2 ? $2.upcase : $1 } : string.upcase
+  end
+
   def enclose_content node
     node.content_model == :compound ? node.content : %(.sp#{LF}#{manify node.content, whitespace: :normalize})
   end