asciidoctor 1.5.8 → 2.0.0.rc.1

data/lib/asciidoctor/rouge_ext.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+require 'rouge' unless defined? Rouge.version
+
+module Asciidoctor; module RougeExt; module Formatters
+  class HTMLTable < ::Rouge::Formatter
+    def initialize delegate, opts
+      @delegate = delegate
+      @start_line = opts[:start_line] || 1
+    end
+
+    def stream tokens
+      formatted_code = @delegate.format tokens
+      formatted_code += LF unless formatted_code.end_with? LF, HangingEndSpanTagCs
+      last_lineno = (first_lineno = @start_line) + (formatted_code.count LF) - 1 # assume number of newlines is constant
+      lineno_format = %(%#{(::Math.log10 last_lineno).floor + 1}i)
+      formatted_linenos = ((first_lineno..last_lineno).map {|lineno| sprintf lineno_format, lineno } << '').join LF
+      yield %(<table class="linenotable"><tbody><tr><td class="linenos gl"><pre class="lineno">#{formatted_linenos}</pre></td><td class="code"><pre>#{formatted_code}</pre></td></tr></tbody></table>)
+    end
+  end
+
+  class HTMLLineHighlighter < ::Rouge::Formatter
+    def initialize delegate, opts
+      @delegate = delegate
+      @lines = opts[:lines] || []
+    end
+
+    def stream tokens
+      lineno = 0
+      token_lines tokens do |tokens_in_line|
+        yield (@lines.include? lineno += 1) ? %(<span class="hll">#{@delegate.format tokens_in_line}#{LF}</span>) : %(#{@delegate.format tokens_in_line}#{LF})
+      end
+    end
+  end
+
+  LF = ?\n
+  HangingEndSpanTagCs = %(#{LF}</span>)
+
+  private_constant :HangingEndSpanTagCs, :LF
+end; end; end

data/lib/asciidoctor/section.rb

@@ -1,4 +1,4 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 module Asciidoctor
 # Public: Methods for managing sections of AsciiDoc content in a document.
 # The section responds as an Array of content blocks by delegating
@@ -130,9 +130,9 @@ class Section < AbstractBlock
         case xrefstyle
         when 'full'
           if (type = @sectname) == 'chapter' || type == 'appendix'
-            quoted_title = sprintf sub_quotes('_%s_'), title
+            quoted_title = sub_placeholder (sub_quotes '_%s_'), title
           else
-            quoted_title = sprintf sub_quotes(@document.compat_mode ? %q(``%s'') : '"`%s`"'), title
+            quoted_title = sub_placeholder (sub_quotes @document.compat_mode ? %q(``%s'') : '"`%s`"'), title
           end
           if (signifier = @document.attributes[%(#{type}-refsig)])
             %(#{signifier} #{sectnum '.', ','} #{quoted_title})
@@ -146,10 +146,10 @@ class Section < AbstractBlock
             sectnum '.', ''
           end
         else # 'basic'
-          (type = @sectname) == 'chapter' || type == 'appendix' ? (sprintf sub_quotes('_%s_'), title) : title
+          (type = @sectname) == 'chapter' || type == 'appendix' ? (sub_placeholder (sub_quotes '_%s_'), title) : title
         end
       else # apply basic styling
-        (type = @sectname) == 'chapter' || type == 'appendix' ? (sprintf sub_quotes('_%s_'), title) : title
+        (type = @sectname) == 'chapter' || type == 'appendix' ? (sub_placeholder (sub_quotes '_%s_'), title) : title
       end
     else
       title
@@ -215,9 +215,10 @@ class Section < AbstractBlock
       # ensure id doesn't begin with idseparator if idprefix is empty (assuming idseparator is not empty)
       gen_id = gen_id.slice 1, gen_id.length if pre.empty? && (gen_id.start_with? sep)
     end
-    if document.catalog[:ids].key? gen_id
-      ids, cnt = document.catalog[:ids], Compliance.unique_id_start_index
-      cnt += 1 while ids.key?(candidate_id = %(#{gen_id}#{sep}#{cnt}))
+    if document.catalog[:refs].key? gen_id
+      ids = document.catalog[:refs]
+      cnt = Compliance.unique_id_start_index
+      cnt += 1 while ids[candidate_id = %(#{gen_id}#{sep}#{cnt})]
       candidate_id
     else
       gen_id

data/lib/asciidoctor/stylesheets.rb

@@ -1,4 +1,4 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 module Asciidoctor
 # A utility class for working with the built-in stylesheets.
 #--
@@ -6,9 +6,7 @@ module Asciidoctor
 # QUESTION create method for user stylesheet?
 class Stylesheets
   DEFAULT_STYLESHEET_NAME = 'asciidoctor.css'
-  DEFAULT_PYGMENTS_STYLE = 'default'
-  STYLESHEETS_DATA_PATH = ::File.join DATA_PATH, 'stylesheets'
-  PygmentsBgColorRx = /^\.pygments +\{ *background: *([^;]+);/
+  STYLESHEETS_DIR = ::File.join DATA_DIR, 'stylesheets'
 
   @__instance__ = new
 
@@ -24,9 +22,12 @@ class Stylesheets
   #
   # returns the [String] Asciidoctor stylesheet data
   def primary_stylesheet_data
-    @primary_stylesheet_data ||= ::IO.read(::File.join(STYLESHEETS_DATA_PATH, 'asciidoctor-default.css')).rstrip
+    @primary_stylesheet_data ||= (::File.read (::File.join STYLESHEETS_DIR, 'asciidoctor-default.css'), mode: FILE_READ_MODE).rstrip
   end
 
+  # Deprecated: Generate code to embed the primary stylesheet
+  #
+  # Returns the [String] primary stylesheet data wrapped in a <style> tag
   def embed_primary_stylesheet
     %(<style>
 #{primary_stylesheet_data}
@@ -34,24 +35,23 @@ class Stylesheets
   end
 
   def write_primary_stylesheet target_dir = '.'
-    ::IO.write(::File.join(target_dir, primary_stylesheet_name), primary_stylesheet_data)
+    ::File.write (::File.join target_dir, primary_stylesheet_name), primary_stylesheet_data, mode: FILE_WRITE_MODE
   end
 
   def coderay_stylesheet_name
-    'coderay-asciidoctor.css'
+    (SyntaxHighlighter.for 'coderay').stylesheet_basename
   end
 
   # Public: Read the contents of the default CodeRay stylesheet
   #
   # returns the [String] CodeRay stylesheet data
   def coderay_stylesheet_data
-    # NOTE use the following lines to load a built-in theme instead
-    # unless load_coderay.nil?
-    #   ::CodeRay::Encoders[:html]::CSS.new(:default).stylesheet
-    # end
-    @coderay_stylesheet_data ||= ::IO.read(::File.join(STYLESHEETS_DATA_PATH, 'coderay-asciidoctor.css')).rstrip
+    (SyntaxHighlighter.for 'coderay').read_stylesheet
   end
 
+  # Deprecated: Generate code to embed the CodeRay stylesheet
+  #
+  # Returns the [String] CodeRay stylesheet data wrapped in a <style> tag
   def embed_coderay_stylesheet
     %(<style>
 #{coderay_stylesheet_data}
@@ -59,33 +59,23 @@ class Stylesheets
   end
 
   def write_coderay_stylesheet target_dir = '.'
-    ::IO.write(::File.join(target_dir, coderay_stylesheet_name), coderay_stylesheet_data)
+    ::File.write (::File.join target_dir, coderay_stylesheet_name), coderay_stylesheet_data, mode: FILE_WRITE_MODE
   end
 
   def pygments_stylesheet_name style = nil
-    %(pygments-#{style || DEFAULT_PYGMENTS_STYLE}.css)
-  end
-
-  def pygments_background style = nil
-    if load_pygments && PygmentsBgColorRx =~ (::Pygments.css '.pygments', :style => style || DEFAULT_PYGMENTS_STYLE)
-      $1
-    end
+    (SyntaxHighlighter.for 'pygments').stylesheet_basename style
   end
 
   # Public: Generate the Pygments stylesheet with the specified style.
   #
   # returns the [String] Pygments stylesheet data
   def pygments_stylesheet_data style = nil
-    if load_pygments
-      style ||= DEFAULT_PYGMENTS_STYLE
-      (@pygments_stylesheet_data ||= {})[style] ||=
-          ((::Pygments.css '.listingblock .pygments', :classprefix => 'tok-', :style => style) || '/* Failed to load Pygments CSS. */').
-          sub('.listingblock .pygments  {', '.listingblock .pygments, .listingblock .pygments code {')
-    else
-      '/* Pygments CSS disabled. Pygments is not available. */'
-    end
+    (SyntaxHighlighter.for 'pygments').read_stylesheet style
   end
 
+  # Deprecated: Generate code to embed the Pygments stylesheet
+  #
+  # Returns the [String] Pygments stylesheet data for the specified style wrapped in a <style> tag
   def embed_pygments_stylesheet style = nil
     %(<style>
 #{pygments_stylesheet_data style}
@@ -93,15 +83,7 @@ class Stylesheets
   end
 
   def write_pygments_stylesheet target_dir = '.', style = nil
-    ::IO.write(::File.join(target_dir, pygments_stylesheet_name(style)), pygments_stylesheet_data(style))
-  end
-
-  #def load_coderay
-  #  (defined? ::CodeRay) ? true : !(Helpers.require_library 'coderay', true, :ignore).nil?
-  #end
-
-  def load_pygments
-    (defined? ::Pygments) ? true : !(Helpers.require_library 'pygments', 'pygments.rb', :ignore).nil?
+    ::File.write (::File.join target_dir, (pygments_stylesheet_name style)), (pygments_stylesheet_data style), mode: FILE_WRITE_MODE
   end
 end
 end

data/lib/asciidoctor/substitutors.rb

@@ -1,4 +1,4 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 module Asciidoctor
 # Public: Methods to perform substitutions on lines of AsciiDoc text. This module
 # is intented to be mixed-in to Section and Block to provide operations for performing
@@ -12,55 +12,45 @@ module Substitutors
 
   (BASIC_SUBS = [:specialcharacters]).freeze
   (HEADER_SUBS = [:specialcharacters, :attributes]).freeze
+  (NO_SUBS = []).freeze
   (NORMAL_SUBS = [:specialcharacters, :quotes, :attributes, :replacements, :macros, :post_replacements]).freeze
-  (NONE_SUBS = []).freeze
-  (TITLE_SUBS = [:specialcharacters, :quotes, :replacements, :macros, :attributes, :post_replacements]).freeze
   (REFTEXT_SUBS = [:specialcharacters, :quotes, :replacements]).freeze
   (VERBATIM_SUBS = [:specialcharacters, :callouts]).freeze
 
   SUB_GROUPS = {
-    :none => NONE_SUBS,
-    :normal => NORMAL_SUBS,
-    :verbatim => VERBATIM_SUBS,
-    :specialchars => BASIC_SUBS
+    none: NO_SUBS,
+    normal: NORMAL_SUBS,
+    verbatim: VERBATIM_SUBS,
+    specialchars: BASIC_SUBS,
   }
 
   SUB_HINTS = {
-    :a => :attributes,
-    :m => :macros,
-    :n => :normal,
-    :p => :post_replacements,
-    :q => :quotes,
-    :r => :replacements,
-    :c => :specialcharacters,
-    :v => :verbatim
+    a: :attributes,
+    m: :macros,
+    n: :normal,
+    p: :post_replacements,
+    q: :quotes,
+    r: :replacements,
+    c: :specialcharacters,
+    v: :verbatim,
   }
 
   SUB_OPTIONS = {
-    :block  => SUB_GROUPS.keys + NORMAL_SUBS + [:callouts],
-    :inline => SUB_GROUPS.keys + NORMAL_SUBS
+    block:  SUB_GROUPS.keys + NORMAL_SUBS + [:callouts],
+    inline: SUB_GROUPS.keys + NORMAL_SUBS,
   }
 
-  SUB_HIGHLIGHT = ['coderay', 'pygments']
+  CAN = ?\u0018
+  DEL = ?\u007f
 
-  if ::RUBY_MIN_VERSION_1_9
-    CAN = %(\u0018)
-    DEL = %(\u007f)
+  # Delimiters and matchers for the passthrough placeholder
+  # See http://www.aivosto.com/vbtips/control-characters.html#listabout for characters to use
 
-    # Delimiters and matchers for the passthrough placeholder
-    # See http://www.aivosto.com/vbtips/control-characters.html#listabout for characters to use
+  # SPA, start of guarded protected area (\u0096)
+  PASS_START = ?\u0096
 
-    # SPA, start of guarded protected area (\u0096)
-    PASS_START = %(\u0096)
-
-    # EPA, end of guarded protected area (\u0097)
-    PASS_END = %(\u0097)
-  else
-    CAN = 24.chr
-    DEL = 127.chr
-    PASS_START = 150.chr
-    PASS_END = 151.chr
-  end
+  # EPA, end of guarded protected area (\u0097)
+  PASS_END = ?\u0097
 
   # match passthrough slot
   PassSlotRx = /#{PASS_START}(\d+)#{PASS_END}/
@@ -76,14 +66,6 @@ module Substitutors
 
   PLUS = '+'
 
-  PygmentsWrapperDivRx = %r(<div class="pyhl">(.*)</div>)m
-  # NOTE handles all permutations of <pre> wrapper
-  # NOTE trailing whitespace appears when pygments-linenums-mode=table; <pre> has style attribute when pygments-css=inline
-  PygmentsWrapperPreRx = %r(<pre\b[^>]*?>(.*?)</pre>\s*)m
-
-  # Internal: A String Array of passthough (unprocessed) text captured from this block
-  attr_reader :passthroughs
-
   # Public: Apply the specified substitutions to the text.
   #
   # text  - The String or String Array of text to process; must not be nil.
@@ -93,14 +75,18 @@ module Substitutors
   def apply_subs text, subs = NORMAL_SUBS
     return text if text.empty? || !subs
 
-    if (multiline = ::Array === text)
-      #text = text.size > 1 ? (text.join LF) : text[0]
+    if (is_multiline = ::Array === text)
       text = text[1] ? (text.join LF) : text[0]
     end
 
-    if (has_passthroughs = subs.include? :macros)
-      text = extract_passthroughs text
-      has_passthroughs = false if @passthroughs.empty?
+    if subs.include? :macros
+      text, passthrus = extract_passthroughs text
+      if passthrus.empty?
+        passthrus = nil
+      else
+        # NOTE placeholders can move around, so we can only clear in the outermost substitution call
+        @passthroughs_locked ||= (reset_passthrus = true)
+      end
     end
 
     subs.each do |type|
@@ -125,9 +111,16 @@ module Substitutors
         logger.warn %(unknown substitution type #{type})
       end
     end
-    text = restore_passthroughs text if has_passthroughs
 
-    multiline ? (text.split LF, -1) : text
+    if passthrus
+      text = restore_passthroughs text
+      if reset_passthrus
+        passthrus.clear
+        @passthroughs_locked = nil
+      end
+    end
+
+    is_multiline ? (text.split LF, -1) : text
   end
 
   # Public: Apply normal substitutions.
@@ -138,7 +131,7 @@ module Substitutors
   #
   # Returns the String with normal substitutions applied.
   def apply_normal_subs text
-    apply_subs text
+    apply_subs text, NORMAL_SUBS
   end
 
   # Public: Apply substitutions for titles.
@@ -146,9 +139,7 @@ module Substitutors
   # title  - The String title to process
   #
   # returns - A String with title substitutions performed
-  def apply_title_subs(title)
-    apply_subs title, TITLE_SUBS
-  end
+  alias apply_title_subs apply_subs
 
   # Public: Apply substitutions for reftext.
   #
@@ -172,33 +163,30 @@ module Substitutors
   #
   # text - The String from which to extract passthrough fragements
   #
-  # returns - The text with the passthrough region substituted with placeholders
+  # returns - A tuple of the String text with passthrough regions substituted with placeholders and the passthroughs Hash
   def extract_passthroughs(text)
     compat_mode = @document.compat_mode
-    passes = @passthroughs
-    text = text.gsub(InlinePassMacroRx) {
-      # alias match for Ruby 1.8.7 compat
-      m = $~
-      preceding = nil
+    passthrus = @passthroughs
+    text = text.gsub InlinePassMacroRx do
+      preceding = ''
 
-      if (boundary = m[4]) # $$, ++, or +++
+      if (boundary = $4) # $$, ++, or +++
         # skip ++ in compat mode, handled as normal quoted text
         if compat_mode && boundary == '++'
-          next m[2] ?
-              %(#{m[1]}[#{m[2]}]#{m[3]}++#{extract_passthroughs m[5]}++) :
-              %(#{m[1]}#{m[3]}++#{extract_passthroughs m[5]}++)
+          content, _ = extract_passthroughs $5
+          next $2 ? %(#{$1}[#{$2}]#{$3}++#{content}++) : %(#{$1}#{$3}++#{content}++)
         end
 
-        attributes = m[2]
-        escape_count = m[3].length
-        content = m[5]
+        attributes = $2
+        escape_count = $3.length
+        content = $5
         old_behavior = false
 
         if attributes
           if escape_count > 0
             # NOTE we don't look for nested unconstrained pass macros
-            next %(#{m[1]}[#{attributes}]#{RS * (escape_count - 1)}#{boundary}#{m[5]}#{boundary})
-          elsif m[1] == RS
+            next %(#{$1}[#{attributes}]#{RS * (escape_count - 1)}#{boundary}#{$5}#{boundary})
+          elsif $1 == RS
             preceding = %([#{attributes}])
             attributes = nil
           else
@@ -210,41 +198,36 @@ module Substitutors
           end
         elsif escape_count > 0
           # NOTE we don't look for nested unconstrained pass macros
-          next %(#{RS * (escape_count - 1)}#{boundary}#{m[5]}#{boundary})
+          next %(#{RS * (escape_count - 1)}#{boundary}#{$5}#{boundary})
         end
         subs = (boundary == '+++' ? [] : BASIC_SUBS)
 
-        pass_key = passes.size
         if attributes
           if old_behavior
-            passes[pass_key] = {:text => content, :subs => NORMAL_SUBS, :type => :monospaced, :attributes => attributes}
+            passthrus[passthru_key = passthrus.size] = { text: content, subs: NORMAL_SUBS, type: :monospaced, attributes: attributes }
           else
-            passes[pass_key] = {:text => content, :subs => subs, :type => :unquoted, :attributes => attributes}
+            passthrus[passthru_key = passthrus.size] = { text: content, subs: subs, type: :unquoted, attributes: attributes }
           end
         else
-          passes[pass_key] = {:text => content, :subs => subs}
+          passthrus[passthru_key = passthrus.size] = { text: content, subs: subs }
         end
       else # pass:[]
-        if m[6] == RS
-          # NOTE we don't look for nested pass:[] macros
-          next m[0].slice 1, m[0].length
-        end
-
-        passes[pass_key = passes.size] = {:text => (unescape_brackets m[8]), :subs => (m[7] ? (resolve_pass_subs m[7]) : nil)}
+        # NOTE we don't look for nested pass:[] macros
+        # honor the escape
+        next $&.slice 1, $&.length if $6 == RS
+        passthrus[passthru_key = passthrus.size] = { text: (unescape_brackets $8), subs: ($7 ? (resolve_pass_subs $7) : nil) }
       end
 
-      %(#{preceding}#{PASS_START}#{pass_key}#{PASS_END})
-    } if (text.include? '++') || (text.include? '$$') || (text.include? 'ss:')
+      %(#{preceding}#{PASS_START}#{passthru_key}#{PASS_END})
+    end if (text.include? '++') || (text.include? '$$') || (text.include? 'ss:')
 
     pass_inline_char1, pass_inline_char2, pass_inline_rx = InlinePassRx[compat_mode]
-    text = text.gsub(pass_inline_rx) {
-      # alias match for Ruby 1.8.7 compat
-      m = $~
-      preceding = m[1]
-      attributes = m[2]
-      escape_mark = RS if (quoted_text = m[3]).start_with? RS
-      format_mark = m[4]
-      content = m[5]
+    text = text.gsub pass_inline_rx do
+      preceding = $1
+      attributes = $2
+      escape_mark = RS if (quoted_text = $3).start_with? RS
+      format_mark = $4
+      content = $5
 
       if compat_mode
         old_behavior = true
@@ -256,11 +239,8 @@ module Substitutors
 
       if attributes
         if format_mark == '`' && !old_behavior
-          # extract nested single-plus passthrough; otherwise return unprocessed
-          next (extract_inner_passthrough content, %(#{preceding}[#{attributes}]#{escape_mark}), attributes)
-        end
-
-        if escape_mark
+          next extract_inner_passthrough content, %(#{preceding}[#{attributes}]#{escape_mark}), attributes
+        elsif escape_mark
           # honor the escape of the formatting mark
           next %(#{preceding}[#{attributes}]#{quoted_text.slice 1, quoted_text.length})
         elsif preceding == RS
@@ -271,60 +251,55 @@ module Substitutors
           attributes = parse_quoted_text_attributes attributes
         end
       elsif format_mark == '`' && !old_behavior
-        # extract nested single-plus passthrough; otherwise return unprocessed
-        next (extract_inner_passthrough content, %(#{preceding}#{escape_mark}))
+        next extract_inner_passthrough content, %(#{preceding}#{escape_mark})
       elsif escape_mark
         # honor the escape of the formatting mark
         next %(#{preceding}#{quoted_text.slice 1, quoted_text.length})
       end
 
-      pass_key = passes.size
       if compat_mode
-        passes[pass_key] = {:text => content, :subs => BASIC_SUBS, :attributes => attributes, :type => :monospaced}
+        passthrus[passthru_key = passthrus.size] = { text: content, subs: BASIC_SUBS, attributes: attributes, type: :monospaced }
       elsif attributes
         if old_behavior
           subs = (format_mark == '`' ? BASIC_SUBS : NORMAL_SUBS)
-          passes[pass_key] = {:text => content, :subs => subs, :attributes => attributes, :type => :monospaced}
+          passthrus[passthru_key = passthrus.size] = { text: content, subs: subs, attributes: attributes, type: :monospaced }
         else
-          passes[pass_key] = {:text => content, :subs => BASIC_SUBS, :attributes => attributes, :type => :unquoted}
+          passthrus[passthru_key = passthrus.size] = { text: content, subs: BASIC_SUBS, attributes: attributes, type: :unquoted }
         end
       else
-        passes[pass_key] = {:text => content, :subs => BASIC_SUBS}
+        passthrus[passthru_key = passthrus.size] = { text: content, subs: BASIC_SUBS }
       end
 
-      %(#{preceding}#{PASS_START}#{pass_key}#{PASS_END})
-    } if (text.include? pass_inline_char1) || (pass_inline_char2 && (text.include? pass_inline_char2))
+      %(#{preceding}#{PASS_START}#{passthru_key}#{PASS_END})
+    end if (text.include? pass_inline_char1) || (pass_inline_char2 && (text.include? pass_inline_char2))
 
     # NOTE we need to do the stem in a subsequent step to allow it to be escaped by the former
-    text = text.gsub(InlineStemMacroRx) {
-      # alias match for Ruby 1.8.7 compat
-      m = $~
+    text = text.gsub InlineStemMacroRx do
       # honor the escape
-      if $&.start_with? RS
-        next m[0].slice 1, m[0].length
-      end
+      next $&.slice 1, $&.length if $&.start_with? RS
 
-      if (type = m[1].to_sym) == :stem
+      if (type = $1.to_sym) == :stem
         type = STEM_TYPE_ALIASES[@document.attributes['stem']].to_sym
       end
-      content = unescape_brackets m[3]
-      subs = m[2] ? (resolve_pass_subs m[2]) : ((@document.basebackend? 'html') ? BASIC_SUBS : nil)
-      passes[pass_key = passes.size] = {:text => content, :subs => subs, :type => type}
-      %(#{PASS_START}#{pass_key}#{PASS_END})
-    } if (text.include? ':') && ((text.include? 'stem:') || (text.include? 'math:'))
+      content = unescape_brackets $3
+      subs = $2 ? (resolve_pass_subs $2) : ((@document.basebackend? 'html') ? BASIC_SUBS : nil)
+      passthrus[passthru_key = passthrus.size] = { text: content, subs: subs, type: type }
+      %(#{PASS_START}#{passthru_key}#{PASS_END})
+    end if (text.include? ':') && ((text.include? 'stem:') || (text.include? 'math:'))
 
-    text
+    [text, passthrus]
   end
 
+  # Internal: Extract nested single-plus passthrough; otherwise return unprocessed
   def extract_inner_passthrough text, pre, attributes = nil
     if (text.end_with? '+') && (text.start_with? '+', '\+') && SinglePlusInlinePassRx =~ text
       if $1
         %(#{pre}`+#{$2}+`)
       else
-        @passthroughs[pass_key = @passthroughs.size] = attributes ?
-            { :text => $2, :subs => BASIC_SUBS, :attributes => attributes, :type => :unquoted } :
-            { :text => $2, :subs => BASIC_SUBS }
-        %(#{pre}`#{PASS_START}#{pass_key}#{PASS_END}`)
+        @passthroughs[passthru_key = @passthroughs.size] = attributes ?
+            { text: $2, subs: BASIC_SUBS, attributes: attributes, type: :unquoted } :
+            { text: $2, subs: BASIC_SUBS }
+        %(#{pre}`#{PASS_START}#{passthru_key}#{PASS_END}`)
       end
     else
       %(#{pre}`#{text}`)
@@ -334,99 +309,71 @@ module Substitutors
   # Internal: Restore the passthrough text by reinserting into the placeholder positions
   #
   # text  - The String text into which to restore the passthrough text
-  # outer - A Boolean indicating whether we are in the outer call (default: true)
   #
   # returns The String text with the passthrough text restored
-  def restore_passthroughs text, outer = true
-    passes = @passthroughs
-    # passthroughs may have been eagerly restored (e.g., footnotes)
-    #if outer && (passes.empty? || !text.include?(PASS_START))
-    #  return text
-    #end
-
-    text.gsub(PassSlotRx) {
-      # NOTE we can't remove entry from map because placeholder may have been duplicated by other substitutions
-      pass = passes[$1.to_i]
-      subbed_text = apply_subs(pass[:text], pass[:subs])
-      if (type = pass[:type])
-        subbed_text = Inline.new(self, :quoted, subbed_text, :type => type, :attributes => pass[:attributes]).convert
-      end
-      subbed_text.include?(PASS_START) ? restore_passthroughs(subbed_text, false) : subbed_text
-    }
-  ensure
-    # free memory if in outer call...we don't need these anymore
-    passes.clear if outer
-  end
-
-  if RUBY_ENGINE == 'opal'
-    def sub_quotes text
-      if QuotedTextSniffRx[compat = @document.compat_mode].match? text
-        QUOTE_SUBS[compat].each do |type, scope, pattern|
-          text = text.gsub(pattern) { convert_quoted_text $~, type, scope }
+  def restore_passthroughs text
+    passthrus = @passthroughs
+    text.gsub PassSlotRx do
+      if (pass = passthrus[$1.to_i])
+        subbed_text = apply_subs(pass[:text], pass[:subs])
+        if (type = pass[:type])
+          subbed_text = Inline.new(self, :quoted, subbed_text, type: type, attributes: pass[:attributes]).convert
         end
+        subbed_text.include?(PASS_START) ? restore_passthroughs(subbed_text) : subbed_text
+      else
+        logger.error %(unresolved passthrough detected: #{text})
+        '??pass??'
       end
-      text
     end
+  end
 
-    def sub_replacements text
-      if ReplaceableTextRx.match? text
-        REPLACEMENTS.each do |pattern, replacement, restore|
-          text = text.gsub(pattern) { do_replacement $~, replacement, restore }
-        end
-      end
-      text
-    end
-  else
-    # Public: Substitute quoted text (includes emphasis, strong, monospaced, etc)
-    #
-    # text - The String text to process
-    #
-    # returns The converted String text
-    def sub_quotes text
-      if QuotedTextSniffRx[compat = @document.compat_mode].match? text
-        # NOTE interpolation is faster than String#dup
-        text = %(#{text})
-        QUOTE_SUBS[compat].each do |type, scope, pattern|
-          # NOTE using gsub! here as an MRI Ruby optimization
-          text.gsub!(pattern) { convert_quoted_text $~, type, scope }
-        end
+  # Public: Substitute quoted text (includes emphasis, strong, monospaced, etc.)
+  #
+  # text - The String text to process
+  #
+  # returns The converted [String] text
+  def sub_quotes text
+    if QuotedTextSniffRx[compat = @document.compat_mode].match? text
+      QUOTE_SUBS[compat].each do |type, scope, pattern|
+        text = text.gsub(pattern) { convert_quoted_text $~, type, scope }
       end
-      text
     end
+    text
+  end
 
-    # Public: Substitute replacement characters (e.g., copyright, trademark, etc)
-    #
-    # text - The String text to process
-    #
-    # returns The String text with the replacement characters substituted
-    def sub_replacements text
-      if ReplaceableTextRx.match? text
-        # NOTE interpolation is faster than String#dup
-        text = %(#{text})
-        REPLACEMENTS.each do |pattern, replacement, restore|
-          # NOTE Using gsub! as optimization
-          text.gsub!(pattern) { do_replacement $~, replacement, restore }
-        end
+  # Public: Substitute replacement characters (e.g., copyright, trademark, etc.)
+  #
+  # text - The String text to process
+  #
+  # returns The [String] text with the replacement characters substituted
+  def sub_replacements text
+    if ReplaceableTextRx.match? text
+      REPLACEMENTS.each do |pattern, replacement, restore|
+        text = text.gsub(pattern) { do_replacement $~, replacement, restore }
       end
-      text
     end
+    text
   end
 
   # Public: Substitute special characters (i.e., encode XML)
   #
-  # The special characters <, &, and > get replaced with &lt;,
-  # &amp;, and &gt;, respectively.
+  # The special characters <, &, and > get replaced with &lt;, &amp;, and &gt;, respectively.
   #
   # text - The String text to process.
   #
   # returns The String text with special characters replaced.
-  if ::RUBY_MIN_VERSION_1_9
+  if RUBY_ENGINE == 'opal'
     def sub_specialchars text
-      (text.include? '<') || (text.include? '&') || (text.include? '>') ? (text.gsub SpecialCharsRx, SpecialCharsTr) : text
+      (text.include? ?>) || (text.include? ?&) || (text.include? ?<) ? (text.gsub SpecialCharsRx, SpecialCharsTr) : text
     end
   else
+    CGI = ::CGI
     def sub_specialchars text
-      (text.include? '<') || (text.include? '&') || (text.include? '>') ? (text.gsub(SpecialCharsRx) { SpecialCharsTr[$&] }) : text
+      if (text.include? ?>) || (text.include? ?&) || (text.include? ?<)
+        (text.include? ?') || (text.include? ?") ? (text.gsub SpecialCharsRx, SpecialCharsTr) : (CGI.escape_html text)
+      else
+        text
+      end
     end
   end
   alias sub_specialcharacters sub_specialchars
@@ -535,7 +482,7 @@ module Substitutors
     #return text if text.nil_or_empty?
     # some look ahead assertions to cut unnecessary regex calls
     found = {}
-    found_square_bracket = found[:square_bracket] = (text.include? '[')
+    found_square_bracket = found[:square_bracket] = text.include? '['
     found_colon = text.include? ':'
     found_macroish = found[:macroish] = found_square_bracket && found_colon
     found_macroish_short = found_macroish && (text.include? ':[')
@@ -543,7 +490,7 @@ module Substitutors
 
     if doc_attrs.key? 'experimental'
       if found_macroish_short && ((text.include? 'kbd:') || (text.include? 'btn:'))
-        text = text.gsub(InlineKbdBtnMacroRx) {
+        text = text.gsub InlineKbdBtnMacroRx do
           # honor the escape
           if $1
             $&.slice 1, $&.length
@@ -564,25 +511,20 @@ module Substitutors
             else
               keys = [keys]
             end
-            (Inline.new self, :kbd, nil, :attributes => { 'keys' => keys }).convert
+            (Inline.new self, :kbd, nil, attributes: { 'keys' => keys }).convert
           else # $2 == 'btn'
             (Inline.new self, :button, (unescape_bracketed_text $3)).convert
           end
-        }
+        end
       end
 
       if found_macroish && (text.include? 'menu:')
-        text = text.gsub(InlineMenuMacroRx) {
-          # alias match for Ruby 1.8.7 compat
-          m = $~
+        text = text.gsub InlineMenuMacroRx do
           # honor the escape
-          if $&.start_with? RS
-            next m[0].slice 1, m[0].length
-          end
-
-          menu, items = m[1], m[2]
+          next $&.slice 1, $&.length if $&.start_with? RS
 
-          if items
+          menu = $1
+          if (items = $2)
             items = items.gsub ESC_R_SB, R_SB if items.include? R_SB
             if (delim = items.include?('&gt;') ? '&gt;' : (items.include?(',') ? ',' : nil))
               submenus = items.split(delim).map {|it| it.strip }
@@ -594,25 +536,19 @@ module Substitutors
             submenus, menuitem = [], nil
           end
 
-          Inline.new(self, :menu, nil, :attributes => {'menu' => menu, 'submenus' => submenus, 'menuitem' => menuitem}).convert
-        }
+          Inline.new(self, :menu, nil, attributes: { 'menu' => menu, 'submenus' => submenus, 'menuitem' => menuitem }).convert
+        end
       end
 
       if (text.include? '"') && (text.include? '&gt;')
-        text = text.gsub(InlineMenuRx) {
-          # alias match for Ruby 1.8.7 compat
-          m = $~
+        text = text.gsub InlineMenuRx do
           # honor the escape
-          if $&.start_with? RS
-            next m[0].slice 1, m[0].length
-          end
-
-          input = m[1]
+          next $&.slice 1, $&.length if $&.start_with? RS
 
-          menu, *submenus = input.split('&gt;').map {|it| it.strip }
+          menu, *submenus = $1.split('&gt;').map {|it| it.strip }
           menuitem = submenus.pop
-          Inline.new(self, :menu, nil, :attributes => {'menu' => menu, 'submenus' => submenus, 'menuitem' => menuitem}).convert
-        }
+          Inline.new(self, :menu, nil, attributes: { 'menu' => menu, 'submenus' => submenus, 'menuitem' => menuitem }).convert
+        end
       end
     end
 
@@ -620,61 +556,55 @@ module Substitutors
     # TODO this handling needs some cleanup
     if (extensions = doc.extensions) && extensions.inline_macros? # && found_macroish
       extensions.inline_macros.each do |extension|
-        text = text.gsub(extension.instance.regexp) {
-          # alias match for Ruby 1.8.7 compat
-          m = $~
+        text = text.gsub extension.instance.regexp do
           # honor the escape
-          if $&.start_with? RS
-            next m[0].slice 1, m[0].length
-          end
-
-          if (m.names rescue []).empty?
-            target, content, extconf = m[1], m[2], extension.config
+          next $&.slice 1, $&.length if $&.start_with? RS
+          extconf = extension.config
+          if $~.names.empty?
+            target, content = $1, $2
           else
-            target, content, extconf = (m[:target] rescue nil), (m[:content] rescue nil), extension.config
+            target, content = ($~[:target] rescue nil), ($~[:content] rescue nil)
           end
           attributes = (attributes = extconf[:default_attrs]) ? attributes.dup : {}
           if content.nil_or_empty?
             attributes['text'] = content if content && extconf[:content_model] != :attributes
           else
             content = unescape_bracketed_text content
+            # QUESTION should we store the unparsed attrlist in the attrlist key?
             if extconf[:content_model] == :attributes
-              # QUESTION should we store the text in the _text key?
-              # NOTE bracked text has already been escaped
-              parse_attributes content, extconf[:pos_attrs] || [], :into => attributes
+              parse_attributes content, extconf[:pos_attrs] || [], into: attributes
             else
               attributes['text'] = content
             end
           end
-          # NOTE use content if target is not set (short form only); deprecated - remove in 1.6.0
-          replacement = extension.process_method[self, target || content, attributes]
+          # NOTE for convenience, map content (unparsed attrlist) to target when format is short
+          target ||= extconf[:format] == :short ? content : target
+          replacement = extension.process_method[self, target, attributes]
           Inline === replacement ? replacement.convert : replacement
-        }
+        end
       end
     end
 
     if found_macroish && ((text.include? 'image:') || (text.include? 'icon:'))
       # image:filename.png[Alt Text]
-      text = text.gsub(InlineImageMacroRx) {
-        # alias match for Ruby 1.8.7 compat
-        m = $~
+      text = text.gsub InlineImageMacroRx do
         # honor the escape
-        if (captured = $&).start_with? RS
-          next captured.slice 1, captured.length
-        elsif captured.start_with? 'icon:'
+        if $&.start_with? RS
+          next $&.slice 1, $&.length
+        elsif $&.start_with? 'icon:'
           type, posattrs = 'icon', ['size']
         else
           type, posattrs = 'image', ['alt', 'width', 'height']
         end
-        if (target = m[1]).include? ATTR_REF_HEAD
+        if (target = $1).include? ATTR_REF_HEAD
           # TODO remove this special case once titles use normal substitution order
           target = sub_attributes target
         end
-        attrs = parse_attributes m[2], posattrs, :unescape_input => true
+        attrs = parse_attributes $2, posattrs, unescape_input: true
         doc.register :images, [target, (attrs['imagesdir'] = doc_attrs['imagesdir'])] unless type == 'icon'
         attrs['alt'] ||= (attrs['default-alt'] = Helpers.basename(target, true).tr('_-', ' '))
-        Inline.new(self, :image, nil, :type => type, :target => target, :attributes => attrs).convert
-      }
+        Inline.new(self, :image, nil, type: type, target: target, attributes: attrs).convert
+      end
     end
 
     if ((text.include? '((') && (text.include? '))')) || (found_macroish_short && (text.include? 'dexterm'))
@@ -682,39 +612,34 @@ module Substitutors
       # indexterm:[Tigers,Big cats]
       # ((Tigers))
       # indexterm2:[Tigers]
-      text = text.gsub(InlineIndextermMacroRx) {
-        captured = $&
+      text = text.gsub InlineIndextermMacroRx do
         case $1
         when 'indexterm'
-          text = $2
           # honor the escape
-          if captured.start_with? RS
-            next captured.slice 1, captured.length
-          end
+          next $&.slice 1, $&.length if $&.start_with? RS
+
           # indexterm:[Tigers,Big cats]
-          terms = split_simple_csv normalize_string text, true
+          terms = split_simple_csv normalize_string $2, true
           doc.register :indexterms, terms
-          (Inline.new self, :indexterm, nil, :attributes => { 'terms' => terms }).convert
+          (Inline.new self, :indexterm, nil, attributes: { 'terms' => terms }).convert
         when 'indexterm2'
-          text = $2
           # honor the escape
-          if captured.start_with? RS
-            next captured.slice 1, captured.length
-          end
+          next $&.slice 1, $&.length if $&.start_with? RS
+
           # indexterm2:[Tigers]
-          term = normalize_string text, true
+          term = normalize_string $2, true
           doc.register :indexterms, [term]
-          (Inline.new self, :indexterm, term, :type => :visible).convert
+          (Inline.new self, :indexterm, term, type: :visible).convert
         else
           text = $3
           # honor the escape
-          if captured.start_with? RS
+          if $&.start_with? RS
             # escape concealed index term, but process nested flow index term
             if (text.start_with? '(') && (text.end_with? ')')
               text = text.slice 1, text.length - 2
               visible, before, after = true, '(', ')'
             else
-              next captured.slice 1, captured.length
+              next $&.slice 1, $&.length
             end
           else
             visible = true
@@ -725,43 +650,41 @@ module Substitutors
                 text, before, after = (text.slice 1, text.length), '(', ''
               end
             elsif text.end_with? ')'
-              text, before, after = (text.slice 0, text.length - 1), '', ')'
+              text, before, after = text.chop, '', ')'
             end
           end
           if visible
             # ((Tigers))
             term = normalize_string text
             doc.register :indexterms, [term]
-            subbed_term = (Inline.new self, :indexterm, term, :type => :visible).convert
+            subbed_term = (Inline.new self, :indexterm, term, type: :visible).convert
           else
             # (((Tigers,Big cats)))
             terms = split_simple_csv(normalize_string text)
             doc.register :indexterms, terms
-            subbed_term = (Inline.new self, :indexterm, nil, :attributes => { 'terms' => terms }).convert
+            subbed_term = (Inline.new self, :indexterm, nil, attributes: { 'terms' => terms }).convert
           end
           before ? %(#{before}#{subbed_term}#{after}) : subbed_term
         end
-      }
+      end
     end
 
     if found_colon && (text.include? '://')
       # inline urls, target[text] (optionally prefixed with link: and optionally surrounded by <>)
-      text = text.gsub(InlineLinkRx) {
-        # alias match for Ruby 1.8.7 compat
-        m = $~
+      text = text.gsub InlineLinkRx do
+        target = $2
         # honor the escape
-        if (target = $2).start_with? RS
-          next %(#{m[1]}#{target.slice 1, target.length}#{m[3]})
-        end
+        next %(#{$1}#{target.slice 1, target.length}#{$3}) if target.start_with? RS
+
         # NOTE if text is non-nil, then we've matched a formal macro (i.e., trailing square brackets)
-        prefix, text, suffix = m[1], (macro = m[3]) || '', ''
+        captured, prefix, text, suffix = $&, $1, (macro = $3) || '', ''
         if prefix == 'link:'
           if macro
             prefix = ''
           else
             # invalid macro syntax (link: prefix w/o trailing square brackets)
             # we probably shouldn't even get here...our regex is doing too much
-            next m[0]
+            next captured
           end
         end
         unless macro || UriTerminatorRx !~ target
@@ -794,10 +717,10 @@ module Substitutors
             end
           end
           # NOTE handle case when remaining target is a URI scheme (e.g., http://)
-          return m[0] if target.end_with? '://'
+          return captured if target.end_with? '://'
         end
 
-        attrs, link_opts = nil, { :type => :link }
+        attrs, link_opts = nil, { type: :link }
         unless text.empty?
           text = text.gsub ESC_R_SB, R_SB if text.include? R_SB
           if !doc.compat_mode && (text.include? '=')
@@ -810,7 +733,7 @@ module Substitutors
           #unless attrs && (attrs.key? 'title')
           #  if text.include? '|'
           #    attrs ||= {}
-          #    text, attrs['title'] = text.split '|', 2
+          #    text, _, attrs['title'] = text.partition '|'
           #  end
           #end
 
@@ -837,21 +760,23 @@ module Substitutors
         doc.register :links, (link_opts[:target] = target)
         link_opts[:attributes] = attrs if attrs
         %(#{prefix}#{Inline.new(self, :anchor, text, link_opts).convert}#{suffix})
-      }
+      end
     end
 
     if found_macroish && ((text.include? 'link:') || (text.include? 'mailto:'))
       # inline link macros, link:target[text]
-      text = text.gsub(InlineLinkMacroRx) {
-        # alias match for Ruby 1.8.7 compat
-        m = $~
+      text = text.gsub InlineLinkMacroRx do
         # honor the escape
         if $&.start_with? RS
-          next m[0].slice 1, m[0].length
+          next $&.slice 1, $&.length
+        elsif (mailto = $1)
+          target = %(mailto:#{$2})
+          mailto_text = $2
+        else
+          target = $2
         end
-        target = (mailto = m[1]) ? %(mailto:#{m[2]}) : m[2]
-        attrs, link_opts = nil, { :type => :link }
-        unless (text = m[3]).empty?
+        attrs, link_opts = nil, { type: :link }
+        unless (text = $3).empty?
           text = text.gsub ESC_R_SB, R_SB if text.include? R_SB
           if mailto
             if !doc.compat_mode && (text.include? ',')
@@ -859,9 +784,9 @@ module Substitutors
               link_opts[:id] = attrs.delete 'id' if attrs.key? 'id'
               if attrs.key? 2
                 if attrs.key? 3
-                  target = %(#{target}?subject=#{Helpers.uri_encode attrs[2]}&amp;body=#{Helpers.uri_encode attrs[3]})
+                  target = %(#{target}?subject=#{Helpers.encode_uri_component attrs[2]}&amp;body=#{Helpers.encode_uri_component attrs[3]})
                 else
-                  target = %(#{target}?subject=#{Helpers.uri_encode attrs[2]})
+                  target = %(#{target}?subject=#{Helpers.encode_uri_component attrs[2]})
                 end
               end
             end
@@ -875,7 +800,7 @@ module Substitutors
           #unless attrs && (attrs.key? 'title')
           #  if text.include? '|'
           #    attrs ||= {}
-          #    text, attrs['title'] = text.split '|', 2
+          #    text, _, attrs['title'] = text.partition '|'
           #  end
           #end
 
@@ -892,7 +817,7 @@ module Substitutors
         if text.empty?
           # mailto is a special case, already processed
           if mailto
-            text = m[2]
+            text = mailto_text
           else
             if doc_attrs.key? 'hide-uri-scheme'
               if (text = target.sub UriSniffRx, '').empty?
@@ -913,41 +838,45 @@ module Substitutors
         doc.register :links, (link_opts[:target] = target)
         link_opts[:attributes] = attrs if attrs
         Inline.new(self, :anchor, text, link_opts).convert
-      }
+      end
     end
 
     if text.include? '@'
-      text = text.gsub(InlineEmailRx) {
-        address, tip = $&, $1
-        if tip
-          next (tip == RS ? (address.slice 1, address.length) : address)
-        end
+      text = text.gsub InlineEmailRx do
+        # honor the escape
+        next $1 == RS ? ($&.slice 1, $&.length) : $& if $1
 
-        target = %(mailto:#{address})
+        target = %(mailto:#{$&})
         # QUESTION should this be registered as an e-mail address?
         doc.register(:links, target)
 
-        Inline.new(self, :anchor, address, :type => :link, :target => target).convert
-      }
+        Inline.new(self, :anchor, $&, type: :link, target: target).convert
+      end
     end
 
     if found_macroish && (text.include? 'tnote')
-      text = text.gsub(InlineFootnoteMacroRx) {
-        # alias match for Ruby 1.8.7 compat
-        m = $~
+      text = text.gsub InlineFootnoteMacroRx do
         # honor the escape
-        if $&.start_with? RS
-          next m[0].slice 1, m[0].length
-        end
-        if m[1] # footnoteref (legacy)
-          id, text = (m[3] || '').split(',', 2)
+        next $&.slice 1, $&.length if $&.start_with? RS
+
+        # footnoteref
+        if $1
+          if $3
+            id, text = $3.split ',', 2
+            logger.warn %(found deprecated footnoteref macro: #{$&}; use footnote macro with target instead) unless doc.compat_mode
+          else
+            next $&
+          end
+        # footnote
         else
-          id, text = m[2], m[3]
+          id = $2
+          text = $3
         end
+
         if id
           if text
             # REVIEW it's a dirty job, but somebody's gotta do it
-            text = restore_passthroughs(sub_inline_xrefs(sub_inline_anchors(normalize_string text, true)), false)
+            text = restore_passthroughs(sub_inline_xrefs(sub_inline_anchors(normalize_string text, true)))
             index = doc.counter('footnote-number')
             doc.register(:footnotes, Document::Footnote.new(index, id, text))
             type, target = :ref, nil
@@ -962,15 +891,15 @@ module Substitutors
           end
         elsif text
           # REVIEW it's a dirty job, but somebody's gotta do it
-          text = restore_passthroughs(sub_inline_xrefs(sub_inline_anchors(normalize_string text, true)), false)
+          text = restore_passthroughs(sub_inline_xrefs(sub_inline_anchors(normalize_string text, true)))
           index = doc.counter('footnote-number')
           doc.register(:footnotes, Document::Footnote.new(index, id, text))
           type = target = nil
         else
-          next m[0]
+          next $&
         end
-        Inline.new(self, :footnote, text, :attributes => {'index' => index}, :id => id, :target => target, :type => type).convert
-      }
+        Inline.new(self, :footnote, text, attributes: { 'index' => index }, id: id, target: target, type: type).convert
+      end
     end
 
     sub_inline_xrefs(sub_inline_anchors(text, found), found)
@@ -979,17 +908,15 @@ module Substitutors
   # Internal: Substitute normal and bibliographic anchors
   def sub_inline_anchors(text, found = nil)
     if @context == :list_item && @parent.style == 'bibliography'
-      text = text.sub(InlineBiblioAnchorRx) {
-        # NOTE target property on :bibref is deprecated
-        Inline.new(self, :anchor, %([#{$2 || $1}]), :type => :bibref, :id => $1, :target => $1).convert
-      }
+      text = text.sub(InlineBiblioAnchorRx) { (Inline.new self, :anchor, $2, type: :bibref, id: $1).convert }
     end
 
     if ((!found || found[:square_bracket]) && text.include?('[[')) ||
         ((!found || found[:macroish]) && text.include?('or:'))
-      text = text.gsub(InlineAnchorRx) {
+      text = text.gsub InlineAnchorRx do
         # honor the escape
         next $&.slice 1, $&.length if $1
+
         # NOTE reftext is only relevant for DocBook output; used as value of xreflabel attribute
         if (id = $2)
           reftext = $3
@@ -999,9 +926,8 @@ module Substitutors
             reftext = reftext.gsub ESC_R_SB, R_SB
           end
         end
-        # NOTE target property on :ref is deprecated
-        Inline.new(self, :anchor, reftext, :type => :ref, :id => id, :target => id).convert
-      }
+        Inline.new(self, :anchor, reftext, type: :ref, id: id).convert
+      end
     end
 
     text
@@ -1010,21 +936,18 @@ module Substitutors
   # Internal: Substitute cross reference links
   def sub_inline_xrefs(content, found = nil)
     if ((found ? found[:macroish] : (content.include? '[')) && (content.include? 'xref:')) || ((content.include? '&') && (content.include? 'lt;&'))
-      content = content.gsub(InlineXrefMacroRx) {
-        # alias match for Ruby 1.8.7 compat
-        m = $~
+      content = content.gsub InlineXrefMacroRx do
         # honor the escape
-        if $&.start_with? RS
-          next m[0].slice 1, m[0].length
-        end
+        next $&.slice 1, $&.length if $&.start_with? RS
+
         attrs, doc = {}, @document
-        if (refid = m[1])
+        if (refid = $1)
           refid, text = refid.split ',', 2
           text = text.lstrip if text
         else
           macro = true
-          refid = m[2]
-          if (text = m[3])
+          refid = $2
+          if (text = $3)
             text = text.gsub ESC_R_SB, R_SB if text.include? R_SB
             # NOTE if an equal sign (=) is present, parse text as attributes
             text = ((AttributeList.new text, self).parse_into attrs)[1] if !doc.compat_mode && (text.include? '=')
@@ -1035,21 +958,27 @@ module Substitutors
           fragment = refid
         elsif (hash_idx = refid.index '#')
           if hash_idx > 0
-            if (fragment_len = refid.length - hash_idx - 1) > 0
+            if (fragment_len = refid.length - 1 - hash_idx) > 0
               path, fragment = (refid.slice 0, hash_idx), (refid.slice hash_idx + 1, fragment_len)
             else
-              path = refid.slice 0, hash_idx
+              path = refid.chop
             end
-            if (ext = ::File.extname path).empty?
+            if macro
+              src2src = (path = path.slice 0, path.length - 5) if path.end_with? '.adoc'
+            elsif (last_dot_idx = path.rindex '.') && ASCIIDOC_EXTENSIONS[path.slice last_dot_idx, path.length]
+              src2src = (path = path.slice 0, last_dot_idx)
+            else
               src2src = path
-            elsif ASCIIDOC_EXTENSIONS[ext]
-              src2src = (path = path.slice 0, path.length - ext.length)
             end
           else
             target, fragment = refid, (refid.slice 1, refid.length)
           end
-        elsif macro && (refid.end_with? '.adoc')
-          src2src = (path = refid.slice 0, refid.length - 5)
+        elsif macro && (refid.include? '.')
+          if refid.end_with? '.adoc'
+            src2src = (path = refid.slice 0, refid.length - 5)
+          else
+            path = refid
+          end
         else
           fragment = refid
         end
@@ -1057,14 +986,14 @@ module Substitutors
         # handles: #id
         if target
           refid = fragment
-          logger.warn %(invalid reference: #{refid}) if $VERBOSE && !(doc.catalog[:ids].key? refid)
+          logger.debug %(possible invalid reference: #{refid}) if logger.debug? && !doc.catalog[:refs][refid]
         elsif path
           # handles: path#, path#id, path.adoc#, path.adoc#id, or path.adoc (xref macro only)
           # the referenced path is the current document, or its contents have been included in the current document
           if src2src && (doc.attributes['docname'] == path || doc.catalog[:includes][path])
             if fragment
               refid, path, target = fragment, nil, %(##{fragment})
-              logger.warn %(invalid reference: #{refid}) if $VERBOSE && !(doc.catalog[:ids].key? refid)
+              logger.debug %(possible invalid reference: #{refid}) if logger.debug? && !doc.catalog[:refs][refid]
             else
               refid, path, target = nil, nil, '#'
             end
@@ -1079,21 +1008,21 @@ module Substitutors
         # handles: id (in compat mode or when natural xrefs are disabled)
         elsif doc.compat_mode || !Compliance.natural_xrefs
           refid, target = fragment, %(##{fragment})
-          logger.warn %(invalid reference: #{refid}) if $VERBOSE && !(doc.catalog[:ids].key? refid)
+          logger.debug %(possible invalid reference: #{refid}) if logger.debug? && doc.catalog[:refs][refid]
         # handles: id
-        elsif doc.catalog[:ids].key? fragment
+        elsif doc.catalog[:refs][fragment]
           refid, target = fragment, %(##{fragment})
         # handles: Node Title or Reference Text
         # do reverse lookup on fragment if not a known ID and resembles reftext (contains a space or uppercase char)
-        elsif (refid = doc.catalog[:ids].key fragment) && ((fragment.include? ' ') || fragment.downcase != fragment)
+        elsif (refid = doc.resolve_id fragment) && ((fragment.include? ' ') || fragment.downcase != fragment)
           fragment, target = refid, %(##{refid})
         else
           refid, target = fragment, %(##{fragment})
-          logger.warn %(invalid reference: #{refid}) if $VERBOSE
+          logger.debug %(possible invalid reference: #{refid}) if logger.debug?
         end
         attrs['path'], attrs['fragment'], attrs['refid'] = path, fragment, refid
-        Inline.new(self, :anchor, text, :type => :xref, :target => target, :attributes => attrs).convert
-      }
+        Inline.new(self, :anchor, text, type: :xref, target: target, attributes: attrs).convert
+      end
     end
 
     content
@@ -1107,15 +1036,15 @@ module Substitutors
   def sub_callouts(text)
     callout_rx = (attr? 'line-comment') ? CalloutSourceRxMap[attr 'line-comment'] : CalloutSourceRx
     autonum = 0
-    text.gsub(callout_rx) {
+    text.gsub callout_rx do
       # honor the escape
       if $2
         # use sub since it might be behind a line comment
         $&.sub(RS, '')
       else
-        Inline.new(self, :callout, $4 == '.' ? (autonum += 1).to_s : $4, :id => @document.callouts.read_next_id, :attributes => { 'guard' => $1 }).convert
+        Inline.new(self, :callout, $4 == '.' ? (autonum += 1).to_s : $4, id: @document.callouts.read_next_id, attributes: { 'guard' => $1 }).convert
       end
-    }
+    end
   end
 
   # Public: Substitute post replacements
@@ -1124,15 +1053,16 @@ module Substitutors
   #
   # Returns the converted String text
   def sub_post_replacements(text)
-    if (@document.attributes.key? 'hardbreaks') || (@attributes.key? 'hardbreaks-option')
+    #if attr? 'hardbreaks-option', nil, true
+    if @attributes['hardbreaks-option'] || @document.attributes['hardbreaks-option']
       lines = text.split LF, -1
       return text if lines.size < 2
       last = lines.pop
-      (lines.map {|line|
-        Inline.new(self, :break, (line.end_with? HARD_LINE_BREAK) ? (line.slice 0, line.length - 2) : line, :type => :line).convert
-      } << last).join LF
+      (lines.map do |line|
+        Inline.new(self, :break, (line.end_with? HARD_LINE_BREAK) ? (line.slice 0, line.length - 2) : line, type: :line).convert
+      end << last).join LF
     elsif (text.include? PLUS) && (text.include? HARD_LINE_BREAK)
-      text.gsub(HardLineBreakRx) { Inline.new(self, :break, $1, :type => :line).convert }
+      text.gsub(HardLineBreakRx) { Inline.new(self, :break, $1, type: :line).convert }
     else
       text
     end
@@ -1156,20 +1086,20 @@ module Substitutors
 
     if scope == :constrained
       if unescaped_attrs
-        %(#{unescaped_attrs}#{Inline.new(self, :quoted, match[3], :type => type).convert})
+        %(#{unescaped_attrs}#{Inline.new(self, :quoted, match[3], type: type).convert})
       else
         if (attrlist = match[2])
           id = (attributes = parse_quoted_text_attributes attrlist).delete 'id'
           type = :unquoted if type == :mark
         end
-        %(#{match[1]}#{Inline.new(self, :quoted, match[3], :type => type, :id => id, :attributes => attributes).convert})
+        %(#{match[1]}#{Inline.new(self, :quoted, match[3], type: type, id: id, attributes: attributes).convert})
       end
     else
       if (attrlist = match[1])
         id = (attributes = parse_quoted_text_attributes attrlist).delete 'id'
         type = :unquoted if type == :mark
       end
-      Inline.new(self, :quoted, match[2], :type => type, :id => id, :attributes => attributes).convert
+      Inline.new(self, :quoted, match[2], type: type, id: id, attributes: attributes).convert
     end
   end
 
@@ -1180,20 +1110,18 @@ module Substitutors
   #
   # Returns a Hash of attributes (role and id only)
   def parse_quoted_text_attributes str
+    return {} if (str = str.rstrip).empty?
     # NOTE attributes are typically resolved after quoted text, so substitute eagerly
     str = sub_attributes str if str.include? ATTR_REF_HEAD
-    # for compliance, only consider first positional attribute
+    # for compliance, only consider first positional attribute (very unlikely)
     str = str.slice 0, (str.index ',') if str.include? ','
 
-    if (str = str.strip).empty?
-      {}
-    elsif (str.start_with? '.', '#') && Compliance.shorthand_property_syntax
-      segments = str.split('#', 2)
+    if (str.start_with? '.', '#') && Compliance.shorthand_property_syntax
+      segments = str.split '#', 2
 
       if segments.size > 1
         id, *more_roles = segments[1].split('.')
       else
-        id = nil
         more_roles = []
       end
 
@@ -1211,7 +1139,7 @@ module Substitutors
       attrs['role'] = roles.join ' ' unless roles.empty?
       attrs
     else
-      {'role' => str}
+      { 'role' => str }
     end
   end
 
@@ -1231,8 +1159,8 @@ module Substitutors
   # Returns an empty Hash if attrlist is nil or empty, otherwise a Hash of parsed attributes.
   def parse_attributes attrlist, posattrs = [], opts = {}
     return {} unless attrlist && !attrlist.empty?
-    attrlist = @document.sub_attributes attrlist if opts[:sub_input] && (attrlist.include? ATTR_REF_HEAD)
     attrlist = unescape_bracketed_text attrlist if opts[:unescape_input]
+    attrlist = @document.sub_attributes attrlist if opts[:sub_input] && (attrlist.include? ATTR_REF_HEAD)
     # substitutions are only performed on attribute values if block is not nil
     block = self if opts[:sub_result]
     if (into = opts[:into])
@@ -1268,7 +1196,7 @@ module Substitutors
     end
   end
 
-  # Internal: Strip bounding whitespace, fold endlines and unescape closing
+  # Internal: Strip bounding whitespace, fold newlines and unescape closing
   # square brackets from text extracted from brackets
   def unescape_bracketed_text text
     if (text = text.strip.tr LF, ' ').include? R_SB
@@ -1277,7 +1205,7 @@ module Substitutors
     text
   end
 
-  # Internal: Strip bounding whitespace and fold endlines
+  # Internal: Strip bounding whitespace and fold newlines
   def normalize_string str, unescape_brackets = false
     unless str.empty?
       str = str.strip.tr LF, ' '
@@ -1299,33 +1227,30 @@ module Substitutors
   # for double-quoted values (in which commas are ignored)
   def split_simple_csv str
     if str.empty?
-      values = []
+      []
     elsif str.include? '"'
       values = []
-      current = []
+      accum = ''
       quote_open = false
       str.each_char do |c|
         case c
         when ','
           if quote_open
-            current << c
+            accum = accum + c
           else
-            values << current.join.strip
-            current = []
+            values << accum.strip
+            accum = ''
           end
         when '"'
           quote_open = !quote_open
         else
-          current << c
+          accum = accum + c
         end
       end
-
-      values << current.join.strip
+      values << accum.strip
     else
-      values = str.split(',').map {|it| it.strip }
+      str.split(',').map {|it| it.strip }
     end
-
-    values
   end
 
   # Internal: Resolve the list of comma-delimited subs against the possible options.
@@ -1403,160 +1328,92 @@ module Substitutors
     resolve_subs subs, :inline, nil, 'passthrough macro'
   end
 
-  # Public: Highlight the source code if a source highlighter is defined
-  # on the document, otherwise return the text unprocessed
+  # Public: Highlight (i.e., colorize) the source code during conversion using a syntax highlighter, if activated by the
+  # source-highlighter document attribute. Otherwise return the text with verbatim substitutions applied.
   #
-  # Callout marks are stripped from the source prior to passing it to the
-  # highlighter, then later restored in converted form, so they are not
-  # incorrectly processed by the source highlighter.
+  # If the process_callouts argument is true, this method will extract the callout marks from the source before passing
+  # it to the syntax highlighter, then subsequently restore those callout marks to the highlighted source so the callout
+  # marks don't confuse the syntax highlighter.
   #
-  # source - the source code String to highlight
-  # process_callouts - a Boolean flag indicating whether callout marks should be substituted
+  # source - the source code String to syntax highlight
+  # process_callouts - a Boolean flag indicating whether callout marks should be located and substituted
   #
-  # returns the highlighted source code, if a source highlighter is defined
-  # on the document, otherwise the source with verbatim substituions applied
-  def highlight_source source, process_callouts, highlighter = nil
-    case (highlighter ||= @document.attributes['source-highlighter'])
-    when 'coderay'
-      unless (highlighter_loaded = defined? ::CodeRay) ||
-          (defined? @@coderay_unavailable) || @document.attributes['coderay-unavailable']
-        if (Helpers.require_library 'coderay', true, :warn).nil?
-          # prevent further attempts to load CodeRay in this process
-          @@coderay_unavailable = true
-        else
-          highlighter_loaded = true
-        end
-      end
-    when 'pygments'
-      unless (highlighter_loaded = defined? ::Pygments) ||
-          (defined? @@pygments_unavailable) || @document.attributes['pygments-unavailable']
-        if (Helpers.require_library 'pygments', 'pygments.rb', :warn).nil?
-          # prevent further attempts to load Pygments in this process
-          @@pygments_unavailable = true
-        else
-          highlighter_loaded = true
-        end
-      end
-    else
-      # unknown highlighting library (something is misconfigured if we arrive here)
-      highlighter_loaded = false
-    end
-
-    return sub_source source, process_callouts unless highlighter_loaded
+  # Returns the highlighted source code, if a syntax highlighter is defined on the document, otherwise the source with
+  # verbatim substituions applied
+  def highlight_source source, process_callouts
+    # NOTE the call to highlight? is a defensive check since, normally, we wouldn't arrive here unless it returns true
+    return sub_source source, process_callouts unless (syntax_hl = @document.syntax_highlighter) && syntax_hl.highlight?
 
-    lineno = 0
-    callout_on_last = false
     if process_callouts
       callout_marks = {}
-      last = -1
+      lineno = 0
+      last_lineno = nil
       callout_rx = (attr? 'line-comment') ? CalloutExtractRxMap[attr 'line-comment'] : CalloutExtractRx
       # extract callout marks, indexed by line number
-      source = source.split(LF, -1).map {|line|
-        lineno = lineno + 1
-        line.gsub(callout_rx) {
+      source = (source.split LF, -1).map do |line|
+        lineno += 1
+        line.gsub callout_rx do
           # honor the escape
           if $2
             # use sub since it might be behind a line comment
-            $&.sub(RS, '')
+            $&.sub RS, ''
           else
             (callout_marks[lineno] ||= []) << [$1, $4]
-            last = lineno
+            last_lineno = lineno
             nil
           end
-        }
-      }.join LF
-      callout_on_last = (last == lineno)
-      callout_marks = nil if callout_marks.empty?
-    else
-      callout_marks = nil
-    end
-
-    linenums_mode = nil
-    highlight_lines = nil
-
-    case highlighter
-    when 'coderay'
-      if (linenums_mode = (attr? 'linenums', nil, false) ? (@document.attributes['coderay-linenums-mode'] || :table).to_sym : nil)
-        start = 1 if (start = (attr 'start', nil, 1).to_i) < 1
-        if attr? 'highlight', nil, false
-          highlight_lines = resolve_lines_to_highlight source, (attr 'highlight', nil, false)
-        end
-      end
-      result = ::CodeRay::Duo[attr('language', :text, false).to_sym, :html, {
-        :css => (@document.attributes['coderay-css'] || :class).to_sym,
-        :line_numbers => linenums_mode,
-        :line_number_start => start,
-        :line_number_anchors => false,
-        :highlight_lines => highlight_lines,
-        :bold_every => false
-      }].highlight source
-    when 'pygments'
-      lexer = ::Pygments::Lexer.find_by_alias(attr 'language', 'text', false) || ::Pygments::Lexer.find_by_mimetype('text/plain')
-      opts = { :cssclass => 'pyhl', :classprefix => 'tok-', :nobackground => true, :stripnl => false }
-      opts[:startinline] = !(option? 'mixed') if lexer.name == 'PHP'
-      unless (@document.attributes['pygments-css'] || 'class') == 'class'
-        opts[:noclasses] = true
-        opts[:style] = (@document.attributes['pygments-style'] || Stylesheets::DEFAULT_PYGMENTS_STYLE)
-      end
-      if attr? 'highlight', nil, false
-        unless (highlight_lines = resolve_lines_to_highlight source, (attr 'highlight', nil, false)).empty?
-          opts[:hl_lines] = highlight_lines.join ' '
-        end
-      end
-      # NOTE highlight can return nil if something goes wrong; fallback to source if this happens
-      # TODO we could add the line numbers in ourselves instead of having to strip out the junk
-      if (attr? 'linenums', nil, false) && (opts[:linenostart] = (start = attr 'start', 1, false).to_i < 1 ? 1 : start) &&
-          (opts[:linenos] = @document.attributes['pygments-linenums-mode'] || 'table') == 'table'
-        linenums_mode = :table
-        if (result = lexer.highlight source, :options => opts)
-          result = (result.sub PygmentsWrapperDivRx, '\1').gsub PygmentsWrapperPreRx, '\1'
-        else
-          result = sub_specialchars source
-        end
-      elsif (result = lexer.highlight source, :options => opts)
-        if PygmentsWrapperPreRx =~ result
-          result = $1
         end
+      end.join LF
+      if last_lineno
+        source = %(#{source}#{LF}) if last_lineno == lineno
       else
-        result = sub_specialchars source
+        callout_marks = nil
       end
     end
 
+    doc_attrs = @document.attributes
+    syntax_hl_name = syntax_hl.name
+    if (linenums_mode = (attr? 'linenums') ? (doc_attrs[%(#{syntax_hl_name}-linenums-mode)] || :table).to_sym : nil)
+      start_line_number = 1 if (start_line_number = (attr 'start', 1).to_i) < 1
+    end
+    highlight_lines = resolve_lines_to_highlight source, (attr 'highlight') if attr? 'highlight'
+
+    highlighted, source_offset = syntax_hl.highlight self, source, (attr 'language'),
+      callouts: callout_marks,
+      css_mode: (doc_attrs[%(#{syntax_hl_name}-css)] || :class).to_sym,
+      highlight_lines: highlight_lines,
+      number_lines: linenums_mode,
+      start_line_number: start_line_number,
+      style: doc_attrs[%(#{syntax_hl_name}-style)]
+
     # fix passthrough placeholders that got caught up in syntax highlighting
-    result = result.gsub HighlightedPassSlotRx, %(#{PASS_START}\\1#{PASS_END}) unless @passthroughs.empty?
+    highlighted = highlighted.gsub HighlightedPassSlotRx, %(#{PASS_START}\\1#{PASS_END}) unless @passthroughs.empty?
 
-    if process_callouts && callout_marks
-      lineno = 0
-      autonum = 0
-      reached_code = linenums_mode != :table
-      result.split(LF, -1).map {|line|
-        unless reached_code
-          next line unless line.include?('<td class="code">')
-          reached_code = true
-        end
-        lineno += 1
-        if (conums = callout_marks.delete(lineno))
-          tail = nil
-          if callout_on_last && callout_marks.empty? && linenums_mode == :table
-            if highlighter == 'coderay' && (pos = line.index '</pre>')
-              line, tail = (line.slice 0, pos), (line.slice pos, line.length)
-            elsif highlighter == 'pygments' && (pos = line.start_with? '</td>')
-              line, tail = '', line
-            end
-          end
+    # NOTE highlight method may have depleted callouts
+    if callout_marks.nil_or_empty?
+      highlighted
+    else
+      if source_offset
+        preamble = highlighted.slice 0, source_offset
+        highlighted = highlighted.slice source_offset, highlighted.length
+      else
+        preamble = ''
+      end
+      autonum = lineno = 0
+      preamble + ((highlighted.split LF, -1).map do |line|
+        if (conums = callout_marks.delete lineno += 1)
           if conums.size == 1
             guard, conum = conums[0]
-            %(#{line}#{Inline.new(self, :callout, conum == '.' ? (autonum += 1).to_s : conum, :id => @document.callouts.read_next_id, :attributes => { 'guard' => guard }).convert}#{tail})
+            %(#{line}#{Inline.new(self, :callout, conum == '.' ? (autonum += 1).to_s : conum, id: @document.callouts.read_next_id, attributes: { 'guard' => guard }).convert})
           else
-            conums_markup = conums.map {|guard_it, conum_it| Inline.new(self, :callout, conum_it == '.' ? (autonum += 1).to_s : conum_it, :id => @document.callouts.read_next_id, :attributes => { 'guard' => guard_it }).convert }.join ' '
-            %(#{line}#{conums_markup}#{tail})
+            %(#{line}#{conums.map do |guard_it, conum_it|
+              Inline.new(self, :callout, conum_it == '.' ? (autonum += 1).to_s : conum_it, id: @document.callouts.read_next_id, attributes: { 'guard' => guard_it }).convert
+            end.join ' '})
           end
         else
           line
         end
-      }.join LF
-    else
-      result
+      end.join LF)
     end
   end
 
@@ -1571,9 +1428,9 @@ module Substitutors
         negate = true
       end
       if (delim = (entry.include? '..') ? '..' : ((entry.include? '-') ? '-' : nil))
-        from, to = entry.split delim, 2
+        from, delim, to = entry.partition delim
         to = (source.count LF) + 1 if to.empty? || (to = to.to_i) < 0
-        line_nums = (::Range.new from.to_i, to).to_a
+        line_nums = (from.to_i..to).to_a
         if negate
           lines -= line_nums
         else
@@ -1600,6 +1457,9 @@ module Substitutors
     process_callouts ? sub_callouts(sub_specialchars source) : (sub_specialchars source)
   end
 
+  # Internal: Inserts text into a formatted text enclosure; used by xreftext
+  alias sub_placeholder sprintf unless RUBY_ENGINE == 'opal'
+
   # Internal: Lock-in the substitutions for this block
   #
   # Looks for an attribute named "subs". If present, resolves substitutions
@@ -1615,16 +1475,11 @@ module Substitutors
       when :simple
         default_subs = NORMAL_SUBS
       when :verbatim
-        if @context == :listing || (@context == :literal && !(option? 'listparagraph'))
-          default_subs = VERBATIM_SUBS
-        elsif @context == :verse
-          default_subs = NORMAL_SUBS
-        else
-          default_subs = BASIC_SUBS
-        end
+        # NOTE :literal with listparagraph-option gets folded into text of list item later
+        default_subs = @context == :verse ? NORMAL_SUBS : VERBATIM_SUBS
       when :raw
         # TODO make pass subs a compliance setting; AsciiDoc Python performs :attributes and :macros on a pass block
-        default_subs = @context == :stem ? BASIC_SUBS : NONE_SUBS
+        default_subs = @context == :stem ? BASIC_SUBS : NO_SUBS
       else
         return @subs
       end
@@ -1637,8 +1492,8 @@ module Substitutors
     end
 
     # QUESION delegate this logic to a method?
-    if @context == :listing && @style == 'source' && (@attributes.key? 'language') && (@document.basebackend? 'html') &&
-        (SUB_HIGHLIGHT.include? @document.attributes['source-highlighter']) && (idx = @subs.index :specialcharacters)
+    if @context == :listing && @style == 'source' && (syntax_hl = @document.syntax_highlighter) &&
+        syntax_hl.highlight? && (idx = @subs.index :specialcharacters)
       @subs[idx] = :highlight
     end