asciidoctor 2.0.0.rc.3 → 2.0.0

data/lib/asciidoctor/converter/html5.rb

@@ -101,7 +101,7 @@ class Converter::Html5Converter < Converter::Base
     result << %(<meta name="application-name" content="#{node.attr 'app-name'}"#{slash}>) if node.attr? 'app-name'
     result << %(<meta name="description" content="#{node.attr 'description'}"#{slash}>) if node.attr? 'description'
     result << %(<meta name="keywords" content="#{node.attr 'keywords'}"#{slash}>) if node.attr? 'keywords'
-    result << %(<meta name="author" content="#{((authors = node.attr 'authors').include? '<') ? (authors.gsub XmlSanitizeRx, '') : authors}"#{slash}>) if node.attr? 'authors'
+    result << %(<meta name="author" content="#{((authors = node.sub_replacements node.attr 'authors').include? '<') ? (authors.gsub XmlSanitizeRx, '') : authors}"#{slash}>) if node.attr? 'authors'
     result << %(<meta name="copyright" content="#{node.attr 'copyright'}"#{slash}>) if node.attr? 'copyright'
     if node.attr? 'favicon'
       if (icon_href = node.attr 'favicon').empty?
@@ -184,7 +184,7 @@ class Converter::Html5Converter < Converter::Base
           details = []
           idx = 1
           node.authors.each do |author|
-            details << %(<span id="author#{idx > 1 ? idx : ''}" class="author">#{author.name}</span>#{br})
+            details << %(<span id="author#{idx > 1 ? idx : ''}" class="author">#{node.sub_replacements author.name}</span>#{br})
             details << %(<span id="email#{idx > 1 ? idx : ''}" class="email">#{node.sub_macros author.email}</span>#{br}) if author.email
             idx += 1
           end

data/lib/asciidoctor/extensions.rb

@@ -143,7 +143,9 @@ module Extensions
       else
         sect.numbered = true if opts.fetch :numbered, (book && (doc.attr? 'partnums'))
       end
-      unless (id = attrs.delete 'id') == false
+      if (id = attrs['id']) == false
+        attrs.delete 'id'
+      else
         sect.id = attrs['id'] = id || ((doc.attr? 'sectids') ? (Section.generate_id sect.title, doc) : nil)
       end
       sect.update_attributes attrs
@@ -211,12 +213,25 @@ module Extensions
     # QUESTION is parse_content the right method name? should we wrap in open block automatically?
     def parse_content parent, content, attributes = nil
       reader = Reader === content ? content : (Reader.new content)
-      while ((block = Parser.next_block reader, parent, (attributes ? attributes.merge : {})) && parent << block) ||
-          reader.has_more_lines?
-      end
+      Parser.parse_blocks reader, parent, attributes
       parent
     end
 
+    # Public: Parses the attrlist String into a Hash of attributes
+    #
+    # block    - the current AbstractBlock or the parent AbstractBlock if there is no current block (used for applying subs)
+    # attrlist - the list of attributes as a String
+    # opts     - an optional Hash of options to control processing:
+    #            :positional_attributes - an Array of attribute names to map positional arguments to (optional, default: false)
+    #            :sub_attributes - enables attribute substitution on the attrlist argument (optional, default: false)
+    #
+    # Returns a Hash of parsed attributes
+    def parse_attributes block, attrlist, opts = {}
+      return {} if attrlist ? attrlist.empty? : true
+      attrlist = block.sub_attributes attrlist if opts[:sub_attributes] && (attrlist.include? ATTR_REF_HEAD)
+      (AttributeList.new attrlist).parse (opts[:positional_attributes] || [])
+    end
+
     # TODO fill out remaining methods
     [
       [:create_paragraph,     :create_block,  :paragraph],
@@ -294,16 +309,17 @@ module Extensions
     alias parse_content_as content_model
 
     def positional_attributes *value
-      option :pos_attrs, value.flatten
+      option :positional_attrs, value.flatten
     end
     alias name_positional_attributes positional_attributes
     # NOTE positional_attrs alias is deprecated
     alias positional_attrs positional_attributes
 
-    def default_attrs value
+    def default_attributes value
       option :default_attrs, value
     end
-    alias default_attributes default_attrs
+    # NOTE default_attrs alias is deprecated
+    alias default_attr default_attributes
 
     def resolve_attributes *args
       # NOTE assume true as default value; rewrap single-argument string or symbol
@@ -312,7 +328,7 @@ module Extensions
       end unless args.size > 1
       case args
       when true
-        option :pos_attrs, []
+        option :positional_attrs, []
         option :default_attrs, {}
       when ::Array
         names, defaults = [], {}
@@ -333,7 +349,7 @@ module Extensions
             names << arg
           end
         end
-        option :pos_attrs, names.compact
+        option :positional_attrs, names.compact
         option :default_attrs, defaults
       when ::Hash
         names, defaults = [], {}
@@ -345,7 +361,7 @@ module Extensions
           end
           defaults[name] = val if val
         end
-        option :pos_attrs, names.compact
+        option :positional_attrs, names.compact
         option :default_attrs, defaults
       else
         raise ::ArgumentError, %(unsupported attributes specification for macro: #{args.inspect})
@@ -507,7 +523,7 @@ module Extensions
   # * :named - The name of the block (required: true)
   # * :contexts - The blocks contexts on which this style can be used (default: [:paragraph, :open]
   # * :content_model - The structure of the content supported in this block (default: :compound)
-  # * :pos_attrs - A list of attribute names used to map positional attributes (default: nil)
+  # * :positional_attrs - A list of attribute names used to map positional attributes (default: nil)
   # * :default_attrs - A hash of attribute names and values used to seed the attributes hash (default: nil)
   # * ...
   #

data/lib/asciidoctor/parser.rb

@@ -41,6 +41,8 @@ class Parser
 
   NoOp = nil
 
+  AuthorKeys = ['author', 'authorinitials', 'firstname', 'middlename', 'lastname', 'email']
+
   # Internal: A Hash mapping horizontal alignment abbreviations to alignments
   # that can be applied to a table cell (or to all cells in a column)
   TableCellHorzAlignments = {
@@ -631,7 +633,7 @@ class Parser
                   end
                 end
                 if extension.config[:content_model] == :attributes
-                  document.parse_attributes content, extension.config[:pos_attrs] || [], sub_input: true, into: attributes if content
+                  document.parse_attributes content, extension.config[:positional_attrs] || [], sub_input: true, into: attributes if content
                 else
                   attributes['text'] = content || ''
                 end
@@ -786,40 +788,27 @@ class Parser
 
     # either delimited block or styled paragraph
     unless block
-      # abstract and partintro should be handled by open block
-      # FIXME kind of hackish...need to sort out how to generalize this
-      block_context = :open if block_context == :abstract || block_context == :partintro
-
       case block_context
-      when :admonition
-        attributes['name'] = admonition_name = style.downcase
-        attributes['textlabel'] = (attributes.delete 'caption') || doc_attrs[%(#{admonition_name}-caption)]
-        block = build_block(block_context, :compound, terminator, parent, reader, attributes)
-
-      when :comment
-        build_block(block_context, :skip, terminator, parent, reader, attributes)
-        attributes.clear
-        return
-
-      when :example
-        block = build_block(block_context, :compound, terminator, parent, reader, attributes)
-
-      when :listing, :literal
-        block = build_block(block_context, :verbatim, terminator, parent, reader, attributes)
-
-      when :source
-        AttributeList.rekey attributes, [nil, 'language', 'linenums']
-        if doc_attrs.key? 'source-language'
-          attributes['language'] = doc_attrs['source-language']
-        end unless attributes.key? 'language'
-        if attributes['linenums-option'] || doc_attrs['source-linenums-option']
-          attributes['linenums'] = ''
-        end unless attributes.key? 'linenums'
-        if doc_attrs.key? 'source-indent'
-          attributes['indent'] = doc_attrs['source-indent']
-        end unless attributes.key? 'indent'
+      when :listing, :source
+        if block_context == :source || (!attributes[1] && (language = attributes[2] || doc_attrs['source-language']))
+          if language
+            attributes['style'] = 'source'
+            attributes['language'] = language
+            AttributeList.rekey attributes, [nil, nil, 'linenums']
+          else
+            AttributeList.rekey attributes, [nil, 'language', 'linenums']
+            if doc_attrs.key? 'source-language'
+              attributes['language'] = doc_attrs['source-language']
+            end unless attributes.key? 'language'
+          end
+          if attributes['linenums-option'] || doc_attrs['source-linenums-option']
+            attributes['linenums'] = ''
+          end unless attributes.key? 'linenums'
+          if doc_attrs.key? 'source-indent'
+            attributes['indent'] = doc_attrs['source-indent']
+          end unless attributes.key? 'indent'
+        end
         block = build_block(:listing, :verbatim, terminator, parent, reader, attributes)
-
       when :fenced_code
         attributes['style'] = 'source'
         if (ll = this_line.length) > 3
@@ -847,17 +836,6 @@ class Parser
         end unless attributes.key? 'indent'
         terminator = terminator.slice 0, 3
         block = build_block(:listing, :verbatim, terminator, parent, reader, attributes)
-
-      when :pass
-        block = build_block(block_context, :raw, terminator, parent, reader, attributes)
-
-      when :stem, :latexmath, :asciimath
-        attributes['style'] = STEM_TYPE_ALIASES[attributes[2] || doc_attrs['stem']] if block_context == :stem
-        block = build_block(:stem, :raw, terminator, parent, reader, attributes)
-
-      when :open, :sidebar
-        block = build_block(block_context, :compound, terminator, parent, reader, attributes)
-
       when :table
         block_cursor = reader.cursor
         block_reader = Reader.new reader.read_lines_until(terminator: terminator, skip_line_comments: true, context: :table, cursor: :at_mark), block_cursor
@@ -867,16 +845,35 @@ class Parser
           attributes['format'] ||= (terminator.start_with? ',') ? 'csv' : 'dsv'
         end
         block = parse_table(block_reader, parent, attributes)
-
+      when :sidebar
+        block = build_block(block_context, :compound, terminator, parent, reader, attributes)
+      when :admonition
+        attributes['name'] = admonition_name = style.downcase
+        attributes['textlabel'] = (attributes.delete 'caption') || doc_attrs[%(#{admonition_name}-caption)]
+        block = build_block(block_context, :compound, terminator, parent, reader, attributes)
+      when :open, :abstract, :partintro
+        block = build_block(:open, :compound, terminator, parent, reader, attributes)
+      when :literal
+        block = build_block(block_context, :verbatim, terminator, parent, reader, attributes)
+      when :example
+        block = build_block(block_context, :compound, terminator, parent, reader, attributes)
       when :quote, :verse
         AttributeList.rekey(attributes, [nil, 'attribution', 'citetitle'])
         block = build_block(block_context, (block_context == :verse ? :verbatim : :compound), terminator, parent, reader, attributes)
-
+      when :stem, :latexmath, :asciimath
+        attributes['style'] = STEM_TYPE_ALIASES[attributes[2] || doc_attrs['stem']] if block_context == :stem
+        block = build_block(:stem, :raw, terminator, parent, reader, attributes)
+      when :pass
+        block = build_block(block_context, :raw, terminator, parent, reader, attributes)
+      when :comment
+        build_block(block_context, :skip, terminator, parent, reader, attributes)
+        attributes.clear
+        return
       else
-        if block_extensions && (extension = extensions.registered_for_block?(block_context, cloaked_context))
+        if block_extensions && (extension = extensions.registered_for_block? block_context, cloaked_context)
           unless (content_model = extension.config[:content_model]) == :skip
-            unless (pos_attrs = extension.config[:pos_attrs] || []).empty?
-              AttributeList.rekey(attributes, [nil] + pos_attrs)
+            unless (positional_attrs = extension.config[:positional_attrs] || []).empty?
+              AttributeList.rekey(attributes, [nil] + positional_attrs)
             end
             if (default_attrs = extension.config[:default_attrs])
               default_attrs.each {|k, v| attributes[k] ||= v }
@@ -884,8 +881,7 @@ class Parser
             # QUESTION should we clone the extension for each cloaked context and set in config?
             attributes['cloaked-context'] = cloaked_context
           end
-          block = build_block block_context, content_model, terminator, parent, reader, attributes, extension: extension
-          unless block
+          unless (block = build_block block_context, content_model, terminator, parent, reader, attributes, extension: extension)
             attributes.clear
             return
           end
@@ -909,7 +905,7 @@ class Parser
       end
     end
     # FIXME remove the need for this update!
-    block.attributes.update(attributes) unless attributes.empty?
+    block.update_attributes attributes unless attributes.empty?
     block.commit_subs
 
     #if doc_attrs.key? :pending_attribute_entries
@@ -1072,9 +1068,13 @@ class Parser
   # parent - The parent Block to which to attach the parsed blocks
   #
   # Returns nothing.
-  def self.parse_blocks(reader, parent)
-    while ((block = next_block reader, parent) && parent.blocks << block) || reader.has_more_lines?
+  def self.parse_blocks(reader, parent, attributes = nil)
+    if attributes
+      while ((block = next_block reader, parent, attributes.merge) && parent.blocks << block) || reader.has_more_lines?; end
+    else
+      while ((block = next_block reader, parent) && parent.blocks << block) || reader.has_more_lines?; end
     end
+    nil
   end
 
   # Internal: Parse and construct an ordered or unordered list at the current position of the Reader
@@ -1127,8 +1127,7 @@ class Parser
   # doc      - The document to which the node belongs; computed from node if not specified
   #
   # Returns nothing
-  def self.catalog_inline_anchor id, reftext, node, location, doc = nil
-    doc = node.document unless doc
+  def self.catalog_inline_anchor id, reftext, node, location, doc = node.document
     reftext = doc.sub_attributes reftext if reftext && (reftext.include? ATTR_REF_HEAD)
     unless doc.register :refs, [id, (Inline.new node, :anchor, reftext, type: :ref, id: id)]
       location = location.cursor if Reader === location
@@ -1318,6 +1317,9 @@ class Parser
         end
       else # :colist
         list_item.marker = sibling_trait
+        if item_text.start_with?('[[') && LeadingInlineAnchorRx =~ item_text
+          catalog_inline_anchor $1, $2, list_item, reader
+        end
       end
     end
 
@@ -1789,9 +1791,8 @@ class Parser
         if document
           # apply header subs and assign to document
           author_metadata.each do |key, val|
-            unless doc_attrs.key? key
-              doc_attrs[key] = ::String === val ? (document.apply_header_subs val) : val
-            end
+            # NOTE the attributes substitution only applies for the email record
+            doc_attrs[key] = ::String === val ? (document.apply_header_subs val) : val unless doc_attrs.key? key
           end
 
           implicit_author = doc_attrs['author']
@@ -1915,20 +1916,13 @@ class Parser
   def self.process_authors author_line, names_only = false, multiple = true
     author_metadata = {}
     author_idx = 0
-    keys = ['author', 'authorinitials', 'firstname', 'middlename', 'lastname', 'email']
-    author_entries = multiple ? (author_line.split ';').map {|it| it.strip } : [*author_line]
-    author_entries.each do |author_entry|
+    (multiple && (author_line.include? ';') ? (author_line.split AuthorDelimiterRx) : [*author_line]).each do |author_entry|
       next if author_entry.empty?
-      author_idx += 1
       key_map = {}
-      if author_idx == 1
-        keys.each do |key|
-          key_map[key.to_sym] = key
-        end
+      if (author_idx += 1) == 1
+        AuthorKeys.each {|key| key_map[key.to_sym] = key }
       else
-        keys.each do |key|
-          key_map[key.to_sym] = %(#{key}_#{author_idx})
-        end
+        AuthorKeys.each {|key| key_map[key.to_sym] = %(#{key}_#{author_idx}) }
       end
 
       if names_only # when parsing an attribute value
@@ -1972,9 +1966,7 @@ class Parser
       else
         # only assign the _1 attributes once we see the second author
         if author_idx == 2
-          keys.each do |key|
-            author_metadata[%(#{key}_1)] = author_metadata[key] if author_metadata.key? key
-          end
+          AuthorKeys.each {|key| author_metadata[%(#{key}_1)] = author_metadata[key] if author_metadata.key? key }
         end
         author_metadata['authors'] = %(#{author_metadata['authors']}, #{author_metadata[key_map[:author]]})
       end

data/lib/asciidoctor/substitutors.rb

@@ -80,12 +80,11 @@ module Substitutors
     end
 
     if subs.include? :macros
-      text, passthrus = extract_passthroughs text
-      if passthrus.empty?
-        passthrus = nil
-      else
+      text = extract_passthroughs text
+      unless @passthroughs.empty?
+        passthrus = @passthroughs
         # NOTE placeholders can move around, so we can only clear in the outermost substitution call
-        @passthroughs_locked ||= (reset_passthrus = true)
+        @passthroughs_locked ||= (clear_passthrus = true)
       end
     end
 
@@ -114,7 +113,7 @@ module Substitutors
 
     if passthrus
       text = restore_passthroughs text
-      if reset_passthrus
+      if clear_passthrus
         passthrus.clear
         @passthroughs_locked = nil
       end
@@ -134,11 +133,20 @@ module Substitutors
     apply_subs text, NORMAL_SUBS
   end
 
+  # Public: Apply substitutions for header metadata and attribute assignments
+  #
+  # text    - String containing the text process
+  #
+  # Returns A String with header substitutions performed
+  def apply_header_subs text
+    apply_subs text, HEADER_SUBS
+  end
+
   # Public: Apply substitutions for titles.
   #
   # title  - The String title to process
   #
-  # returns - A String with title substitutions performed
+  # Returns A String with title substitutions performed
   alias apply_title_subs apply_subs
 
   # Public: Apply substitutions for reftext.
@@ -150,223 +158,13 @@ module Substitutors
     apply_subs text, REFTEXT_SUBS
   end
 
-  # Public: Apply substitutions for header metadata and attribute assignments
-  #
-  # text    - String containing the text process
-  #
-  # returns - A String with header substitutions performed
-  def apply_header_subs(text)
-    apply_subs text, HEADER_SUBS
-  end
-
-  # Internal: Extract the passthrough text from the document for reinsertion after processing.
-  #
-  # text - The String from which to extract passthrough fragements
-  #
-  # 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
-    passthrus = @passthroughs
-    text = text.gsub InlinePassMacroRx do
-      preceding = ''
-
-      if (boundary = $4) # $$, ++, or +++
-        # skip ++ in compat mode, handled as normal quoted text
-        if compat_mode && boundary == '++'
-          content, _ = extract_passthroughs $5
-          next $2 ? %(#{$1}[#{$2}]#{$3}++#{content}++) : %(#{$1}#{$3}++#{content}++)
-        end
-
-        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 %(#{$1}[#{attributes}]#{RS * (escape_count - 1)}#{boundary}#{$5}#{boundary})
-          elsif $1 == RS
-            preceding = %([#{attributes}])
-            attributes = nil
-          else
-            if boundary == '++' && (attributes.end_with? 'x-')
-              old_behavior = true
-              attributes = attributes.slice 0, attributes.length - 2
-            end
-            attributes = parse_quoted_text_attributes attributes
-          end
-        elsif escape_count > 0
-          # NOTE we don't look for nested unconstrained pass macros
-          next %(#{RS * (escape_count - 1)}#{boundary}#{$5}#{boundary})
-        end
-        subs = (boundary == '+++' ? [] : BASIC_SUBS)
-
-        if attributes
-          if old_behavior
-            passthrus[passthru_key = passthrus.size] = { text: content, subs: NORMAL_SUBS, type: :monospaced, attributes: attributes }
-          else
-            passthrus[passthru_key = passthrus.size] = { text: content, subs: subs, type: :unquoted, attributes: attributes }
-          end
-        else
-          passthrus[passthru_key = passthrus.size] = { text: content, subs: subs }
-        end
-      else # pass:[]
-        # 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}#{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 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
-      else
-        if (old_behavior = attributes && (attributes.end_with? 'x-'))
-          attributes = attributes.slice 0, attributes.length - 2
-        end
-      end
-
-      if attributes
-        if format_mark == '`' && !old_behavior
-          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
-          # honor the escape of the attributes
-          preceding = %([#{attributes}])
-          attributes = nil
-        else
-          attributes = parse_quoted_text_attributes attributes
-        end
-      elsif format_mark == '`' && !old_behavior
-        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
-
-      if compat_mode
-        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)
-          passthrus[passthru_key = passthrus.size] = { text: content, subs: subs, attributes: attributes, type: :monospaced }
-        else
-          passthrus[passthru_key = passthrus.size] = { text: content, subs: BASIC_SUBS, attributes: attributes, type: :unquoted }
-        end
-      else
-        passthrus[passthru_key = passthrus.size] = { text: content, subs: BASIC_SUBS }
-      end
-
-      %(#{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 do
-      # honor the escape
-      next $&.slice 1, $&.length if $&.start_with? RS
-
-      if (type = $1.to_sym) == :stem
-        type = STEM_TYPE_ALIASES[@document.attributes['stem']].to_sym
-      end
-      content = unescape_brackets $3
-      # NOTE for backwards compatibility with AsciiDoc Python, drop enclosing $ signs around latexmath
-      content = content.slice 1, content.length - 2 if type == :latexmath && (content.start_with? '$') && (content.end_with? '$')
-      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, 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[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}`)
-    end
-  end
-
-  # Internal: Restore the passthrough text by reinserting into the placeholder positions
-  #
-  # text  - The String text into which to restore the passthrough text
-  #
-  # returns The String text with the passthrough text restored
-  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])
-          if (attributes = pass[:attributes])
-            id = attributes.delete 'id'
-          end
-          subbed_text = Inline.new(self, :quoted, subbed_text, type: type, id: id, attributes: attributes).convert
-        end
-        subbed_text.include?(PASS_START) ? restore_passthroughs(subbed_text) : subbed_text
-      else
-        logger.error %(unresolved passthrough detected: #{text})
-        '??pass??'
-      end
-    end
-  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
-    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
-      REPLACEMENTS.each do |pattern, replacement, restore|
-        text = text.gsub(pattern) { do_replacement $~, replacement, restore }
-      end
-    end
-    text
-  end
-
   # Public: Substitute special characters (i.e., encode XML)
   #
   # 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.
+  # Returns The String text with special characters replaced.
   if RUBY_ENGINE == 'opal'
     def sub_specialchars text
       (text.include? ?>) || (text.include? ?&) || (text.include? ?<) ? (text.gsub SpecialCharsRx, SpecialCharsTr) : text
@@ -383,23 +181,18 @@ module Substitutors
   end
   alias sub_specialcharacters sub_specialchars
 
-  # Internal: Substitute replacement text for matched location
+  # Public: Substitute quoted text (includes emphasis, strong, monospaced, etc.)
   #
-  # returns The String text with the replacement characters substituted
-  def do_replacement m, replacement, restore
-    if (captured = m[0]).include? RS
-      # we have to use sub since we aren't sure it's the first char
-      captured.sub RS, ''
-    else
-      case restore
-      when :none
-        replacement
-      when :bounding
-        m[1] + replacement + m[2]
-      else # :leading
-        m[1] + replacement
+  # 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
     end
+    text
   end
 
   # Public: Substitutes attribute references in the specified text
@@ -411,7 +204,8 @@ module Substitutors
   #
   # text - The String text to process
   # opts - A Hash of options to control processing: (default: {})
-  #        * :attribute_missing controls how to handle a missing attribute
+  #        * :attribute_missing controls how to handle a missing attribute (see Compliance.attribute_missing for values)
+  #        * :drop_line_severity the severity level at which to log a dropped line (:info or :ignore)
   #
   # Returns the [String] text with the attribute references replaced with resolved values
   def sub_attributes text, opts = {}
@@ -480,6 +274,18 @@ module Substitutors
     end
   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
+    REPLACEMENTS.each do |pattern, replacement, restore|
+      text = text.gsub(pattern) { do_replacement $~, replacement, restore }
+    end if ReplaceableTextRx.match? text
+    text
+  end
+
   # Public: Substitute inline macros (e.g., links, images, etc)
   #
   # Replace inline macros, which may span multiple lines, in the provided text
@@ -487,7 +293,7 @@ module Substitutors
   # source - The String text to process
   #
   # returns The converted String text
-  def sub_macros(text)
+  def sub_macros text
     #return text if text.nil_or_empty?
     # some look ahead assertions to cut unnecessary regex calls
     found_square_bracket = text.include? '['
@@ -513,10 +319,10 @@ module Substitutors
           if content.nil_or_empty?
             attributes['text'] = content if content && extconf[:content_model] != :attributes
           else
-            content = unescape_bracketed_text content
+            content = normalize_text content, true, true
             # QUESTION should we store the unparsed attrlist in the attrlist key?
             if extconf[:content_model] == :attributes
-              parse_attributes content, extconf[:pos_attrs] || [], into: attributes
+              parse_attributes content, extconf[:positional_attrs] || [], into: attributes
             else
               attributes['text'] = content
             end
@@ -563,7 +369,7 @@ module Substitutors
             end
             (Inline.new self, :kbd, nil, attributes: { 'keys' => keys }).convert
           else # $2 == 'btn'
-            (Inline.new self, :button, (unescape_bracketed_text $3)).convert
+            (Inline.new self, :button, (normalize_text $3, true, true)).convert
           end
         end
       end
@@ -613,10 +419,7 @@ module Substitutors
         else
           type, posattrs = 'image', ['alt', 'width', 'height']
         end
-        if (target = $1).include? ATTR_REF_HEAD
-          # TODO remove this special case once titles use normal substitution order
-          target = sub_attributes target
-        end
+        target = $1
         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('_-', ' '))
@@ -636,17 +439,39 @@ module Substitutors
           next $&.slice 1, $&.length if $&.start_with? RS
 
           # indexterm:[Tigers,Big cats]
-          terms = split_simple_csv normalize_string $2, true
+          if (attrlist = normalize_text $2, true, true).include? '='
+            if (primary = (attrs = (AttributeList.new attrlist, self).parse)[1])
+              attrs['terms'] = terms = [primary]
+              if (secondary = attrs[2])
+                terms << secondary
+                if (tertiary = attrs[3])
+                  terms << tertiary
+                end
+              end
+              if (see_also = attrs['see-also'])
+                attrs['see-also'] = (see_also.include? ',') ? (see_also.split ',').map {|it| it.lstrip } : [see_also]
+              end
+            else
+              attrs = { 'terms' => (terms = attrlist) }
+            end
+          else
+            attrs = { 'terms' => (terms = split_simple_csv attrlist) }
+          end
           #doc.register :indexterms, terms
-          (Inline.new self, :indexterm, nil, attributes: { 'terms' => terms }).convert
+          (Inline.new self, :indexterm, nil, attributes: attrs).convert
         when 'indexterm2'
           # honor the escape
           next $&.slice 1, $&.length if $&.start_with? RS
 
           # indexterm2:[Tigers]
-          term = normalize_string $2, true
+          if (term = normalize_text $2, true, true).include? '='
+            term = (attrs = (AttributeList.new term, self).parse)[1] || (attrs = nil) || term
+            if attrs && (see_also = attrs['see-also'])
+              attrs['see-also'] = (see_also.include? ',') ? (see_also.split ',').map {|it| it.lstrip } : [see_also]
+            end
+          end
           #doc.register :indexterms, [term]
-          (Inline.new self, :indexterm, term, type: :visible).convert
+          (Inline.new self, :indexterm, term, attributes: attrs, type: :visible).convert
         else
           text = $3
           # honor the escape
@@ -672,14 +497,32 @@ module Substitutors
           end
           if visible
             # ((Tigers))
-            term = normalize_string text
+            if (term = normalize_text text, true).include? ';&'
+              if term.include? ' &gt;&gt; '
+                term, _, see = term.partition ' &gt;&gt; '
+                attrs = { 'see' => see }
+              elsif term.include? ' &amp;&gt; '
+                term, *see_also = term.split ' &amp;&gt; '
+                attrs = { 'see-also' => see_also }
+              end
+            end
             #doc.register :indexterms, [term]
-            subbed_term = (Inline.new self, :indexterm, term, type: :visible).convert
+            subbed_term = (Inline.new self, :indexterm, term, attributes: attrs, type: :visible).convert
           else
             # (((Tigers,Big cats)))
-            terms = split_simple_csv(normalize_string text)
+            attrs = {}
+            if (terms = normalize_text text, true).include? ';&'
+              if terms.include? ' &gt;&gt; '
+                terms, _, see = terms.partition ' &gt;&gt; '
+                attrs['see'] = see
+              elsif terms.include? ' &amp;&gt; '
+                terms, *see_also = terms.split ' &amp;&gt; '
+                attrs['see-also'] = see_also
+              end
+            end
+            attrs['terms'] = terms = split_simple_csv terms
             #doc.register :indexterms, terms
-            subbed_term = (Inline.new self, :indexterm, nil, attributes: { 'terms' => terms }).convert
+            subbed_term = (Inline.new self, :indexterm, nil, attributes: attrs).convert
           end
           before ? %(#{before}#{subbed_term}#{after}) : subbed_term
         end
@@ -745,18 +588,9 @@ module Substitutors
           text = text.gsub ESC_R_SB, R_SB if text.include? R_SB
           if !doc.compat_mode && (text.include? '=')
             text = (attrs = (AttributeList.new text, self).parse)[1] || ''
-            link_opts[:id] = attrs.delete 'id' if attrs.key? 'id'
+            link_opts[:id] = attrs['id']
           end
 
-          # TODO enable in Asciidoctor 1.6.x
-          # support pipe-separated text and title
-          #unless attrs && (attrs.key? 'title')
-          #  if text.include? '|'
-          #    attrs ||= {}
-          #    text, _, attrs['title'] = text.partition '|'
-          #  end
-          #end
-
           if text.end_with? '^'
             text = text.chop
             if attrs
@@ -800,7 +634,7 @@ module Substitutors
           if mailto
             if !doc.compat_mode && (text.include? ',')
               text = (attrs = (AttributeList.new text, self).parse)[1] || ''
-              link_opts[:id] = attrs.delete 'id' if attrs.key? 'id'
+              link_opts[:id] = attrs['id']
               if attrs.key? 2
                 if attrs.key? 3
                   target = %(#{target}?subject=#{Helpers.encode_uri_component attrs[2]}&amp;body=#{Helpers.encode_uri_component attrs[3]})
@@ -811,18 +645,9 @@ module Substitutors
             end
           elsif !doc.compat_mode && (text.include? '=')
             text = (attrs = (AttributeList.new text, self).parse)[1] || ''
-            link_opts[:id] = attrs.delete 'id' if attrs.key? 'id'
+            link_opts[:id] = attrs['id']
           end
 
-          # TODO enable in Asciidoctor 1.6.x
-          # support pipe-separated text and title
-          #unless attrs && (attrs.key? 'title')
-          #  if text.include? '|'
-          #    attrs ||= {}
-          #    text, _, attrs['title'] = text.partition '|'
-          #  end
-          #end
-
           if text.end_with? '^'
             text = text.chop
             if attrs
@@ -1009,7 +834,7 @@ module Substitutors
 
         if id
           if text
-            text = restore_passthroughs(normalize_string text, true)
+            text = restore_passthroughs(normalize_text text, true, true)
             index = doc.counter('footnote-number')
             doc.register(:footnotes, Document::Footnote.new(index, id, text))
             type, target = :ref, nil
@@ -1023,7 +848,7 @@ module Substitutors
             type, target, id = :xref, id, nil
           end
         elsif text
-          text = restore_passthroughs(normalize_string text, true)
+          text = restore_passthroughs(normalize_text text, true, true)
           index = doc.counter('footnote-number')
           doc.register(:footnotes, Document::Footnote.new(index, id, text))
           type = target = nil
@@ -1037,31 +862,12 @@ module Substitutors
     text
   end
 
-  # Public: Substitute callout source references
+  # Public: Substitute post replacements
   #
   # text - The String text to process
   #
   # Returns the converted String text
-  def sub_callouts(text)
-    callout_rx = (attr? 'line-comment') ? CalloutSourceRxMap[attr 'line-comment'] : CalloutSourceRx
-    autonum = 0
-    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
-      end
-    end
-  end
-
-  # Public: Substitute post replacements
-  #
-  # text - The String text to process
-  #
-  # Returns the converted String text
-  def sub_post_replacements(text)
+  def sub_post_replacements text
     #if attr? 'hardbreaks-option', nil, true
     if @attributes['hardbreaks-option'] || @document.attributes['hardbreaks-option']
       lines = text.split LF, -1
@@ -1077,196 +883,271 @@ module Substitutors
     end
   end
 
-  # Internal: Convert a quoted text region
+  # Public: Apply verbatim substitutions on source (for use when highlighting is disabled).
   #
-  # match  - The MatchData for the quoted text region
-  # type   - The quoting type (single, double, strong, emphasis, monospaced, etc)
-  # scope  - The scope of the quoting (constrained or unconstrained)
+  # source - the source code String on which to apply verbatim substitutions
+  # process_callouts - a Boolean flag indicating whether callout marks should be substituted
   #
-  # Returns The converted String text for the quoted text region
-  def convert_quoted_text(match, type, scope)
-    if match[0].start_with? RS
-      if scope == :constrained && (attrs = match[2])
-        unescaped_attrs = %([#{attrs}])
-      else
-        return match[0].slice 1, match[0].length
-      end
-    end
+  # Returns the substituted source
+  def sub_source source, process_callouts
+    process_callouts ? sub_callouts(sub_specialchars source) : (sub_specialchars source)
+  end
 
-    if scope == :constrained
-      if unescaped_attrs
-        %(#{unescaped_attrs}#{Inline.new(self, :quoted, match[3], type: type).convert})
+  # Public: Substitute callout source references
+  #
+  # text - The String text to process
+  #
+  # Returns the converted String text
+  def sub_callouts text
+    callout_rx = (attr? 'line-comment') ? CalloutSourceRxMap[attr 'line-comment'] : CalloutSourceRx
+    autonum = 0
+    text.gsub callout_rx do
+      # honor the escape
+      if $2
+        # use sub since it might be behind a line comment
+        $&.sub(RS, '')
       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})
-      end
-    else
-      if (attrlist = match[1])
-        id = (attributes = parse_quoted_text_attributes attrlist).delete 'id'
-        type = :unquoted if type == :mark
+        Inline.new(self, :callout, $4 == '.' ? (autonum += 1).to_s : $4, id: @document.callouts.read_next_id, attributes: { 'guard' => $1 }).convert
       end
-      Inline.new(self, :quoted, match[2], type: type, id: id, attributes: attributes).convert
     end
   end
 
-  # Internal: Parse the attributes that are defined on quoted (aka formatted) text
+  # 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.
   #
-  # str - A non-nil String of unprocessed attributes;
-  #       space-separated roles (e.g., role1 role2) or the id/role shorthand syntax (e.g., #idname.role)
+  # 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.
   #
-  # 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 (very unlikely)
-    str = str.slice 0, (str.index ',') if str.include? ','
+  # 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 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?
 
-    if (str.start_with? '.', '#') && Compliance.shorthand_property_syntax
-      segments = str.split '#', 2
+    source, callout_marks = extract_callouts source if process_callouts
 
-      if segments.size > 1
-        id, *more_roles = segments[1].split('.')
-      else
-        more_roles = []
-      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'
 
-      roles = segments[0].empty? ? [] : segments[0].split('.')
-      if roles.size > 1
-        roles.shift
-      end
+    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)]
 
-      if more_roles.size > 0
-        roles.concat more_roles
-      end
+    # fix passthrough placeholders that got caught up in syntax highlighting
+    highlighted = highlighted.gsub HighlightedPassSlotRx, %(#{PASS_START}\\1#{PASS_END}) unless @passthroughs.empty?
 
-      attrs = {}
-      attrs['id'] = id if id
-      attrs['role'] = roles.join ' ' unless roles.empty?
-      attrs
-    else
-      { 'role' => str }
-    end
+    # NOTE highlight method may have depleted callouts
+    callout_marks.nil_or_empty? ? highlighted : (restore_callouts highlighted, callout_marks, source_offset)
   end
 
-  # Internal: Parse attributes in name or name=value format from a comma-separated String
+  # Public: Resolve the line numbers in the specified source to highlight from the provided spec.
   #
-  # attrlist - A comma-separated String list of attributes in name or name=value format.
-  # posattrs - An Array of positional attribute names (default: []).
-  # opts     - A Hash of options to control how the string is parsed (default: {}):
-  #            :into           - The Hash to parse the attributes into (optional, default: false).
-  #            :sub_input      - A Boolean that indicates whether to substitute attributes prior to
-  #                              parsing (optional, default: false).
-  #            :sub_result     - A Boolean that indicates whether to apply substitutions
-  #                              single-quoted attribute values (optional, default: true).
-  #            :unescape_input - A Boolean that indicates whether to unescape square brackets prior
-  #                              to parsing (optional, default: false).
+  # e.g., highlight="1-5, !2, 10" or highlight=1-5;!2,10
   #
-  # 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 = 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])
-      AttributeList.new(attrlist, block).parse_into(into, posattrs)
-    else
-      AttributeList.new(attrlist, block).parse(posattrs)
+  # source - The String source.
+  # spec   - The lines specifier (e.g., "1-5, !2, 10" or "1..5;!2;10")
+  #
+  # Returns an [Array] of unique, sorted line numbers.
+  def resolve_lines_to_highlight source, spec
+    lines = []
+    spec = spec.delete ' ' if spec.include? ' '
+    ((spec.include? ',') ? (spec.split ',') : (spec.split ';')).map do |entry|
+      if entry.start_with? '!'
+        entry = entry.slice 1, entry.length
+        negate = true
+      end
+      if (delim = (entry.include? '..') ? '..' : ((entry.include? '-') ? '-' : nil))
+        from, delim, to = entry.partition delim
+        to = (source.count LF) + 1 if to.empty? || (to = to.to_i) < 0
+        line_nums = (from.to_i..to).to_a
+        if negate
+          lines -= line_nums
+        else
+          lines.concat line_nums
+        end
+      else
+        if negate
+          lines.delete entry.to_i
+        else
+          lines << entry.to_i
+        end
+      end
     end
+    lines.sort.uniq
   end
 
-  # Expand all groups in the subs list and return. If no subs are resolve, return nil.
+  # Public: Extract the passthrough text from the document for reinsertion after processing.
   #
-  # subs - The substitutions to expand; can be a Symbol, Symbol Array or nil
+  # text - The String from which to extract passthrough fragements
   #
-  # Returns a Symbol Array of substitutions to pass to apply_subs or nil if no substitutions were resolved.
-  def expand_subs subs
-    if ::Symbol === subs
-      unless subs == :none
-        SUB_GROUPS[subs] || [subs]
-      end
-    else
-      expanded_subs = []
-      subs.each do |key|
-        unless key == :none
-          if (sub_group = SUB_GROUPS[key])
-            expanded_subs += sub_group
+  # Returns the String text with passthrough regions substituted with placeholders
+  def extract_passthroughs text
+    compat_mode = @document.compat_mode
+    passthrus = @passthroughs
+    text = text.gsub InlinePassMacroRx do
+      if (boundary = $4) # $$, ++, or +++
+        # skip ++ in compat mode, handled as normal quoted text
+        if compat_mode && boundary == '++'
+          content = extract_passthroughs $5
+          next $2 ? %(#{$1}[#{$2}]#{$3}++#{content}++) : %(#{$1}#{$3}++#{content}++)
+        end
+
+        attributes = $2
+        escape_count = $3.length
+        content = $5
+
+        if attributes
+          if escape_count > 0
+            # NOTE we don't look for nested unconstrained pass macros
+            next %(#{$1}[#{attributes}]#{RS * (escape_count - 1)}#{boundary}#{$5}#{boundary})
+          elsif $1 == RS
+            preceding = %([#{attributes}])
+            attributes = nil
           else
-            expanded_subs << key
+            if boundary == '++' && (attributes.end_with? 'x-')
+              old_behavior = true
+              attributes = attributes.slice 0, attributes.length - 2
+            end
+            attributes = parse_quoted_text_attributes attributes
           end
+        elsif escape_count > 0
+          # NOTE we don't look for nested unconstrained pass macros
+          next %(#{RS * (escape_count - 1)}#{boundary}#{$5}#{boundary})
         end
+        subs = (boundary == '+++' ? [] : BASIC_SUBS)
+
+        if attributes
+          if old_behavior
+            passthrus[passthru_key = passthrus.size] = { text: content, subs: NORMAL_SUBS, type: :monospaced, attributes: attributes }
+          else
+            passthrus[passthru_key = passthrus.size] = { text: content, subs: subs, type: :unquoted, attributes: attributes }
+          end
+        else
+          passthrus[passthru_key = passthrus.size] = { text: content, subs: subs }
+        end
+      else # pass:[]
+        # 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: (normalize_text $8, nil, true), subs: ($7 ? (resolve_pass_subs $7) : nil) }
       end
 
-      expanded_subs.empty? ? nil : expanded_subs
-    end
-  end
+      %(#{preceding || ''}#{PASS_START}#{passthru_key}#{PASS_END})
+    end if (text.include? '++') || (text.include? '$$') || (text.include? 'ss:')
 
-  # 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
-      text = text.gsub ESC_R_SB, R_SB
-    end unless text.empty?
-    text
-  end
+    pass_inline_char1, pass_inline_char2, pass_inline_rx = InlinePassRx[compat_mode]
+    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
 
-  # Internal: Strip bounding whitespace and fold newlines
-  def normalize_string str, unescape_brackets = false
-    unless str.empty?
-      str = str.strip.tr LF, ' '
-      str = str.gsub ESC_R_SB, R_SB if unescape_brackets && (str.include? R_SB)
-    end
-    str
-  end
+      if compat_mode
+        old_behavior = true
+      elsif (old_behavior = attributes && (attributes.end_with? 'x-'))
+        attributes = attributes.slice 0, attributes.length - 2
+      end
 
-  # Internal: Unescape closing square brackets.
-  # Intended for text extracted from square brackets.
-  def unescape_brackets str
-    if str.include? RS
-      str = str.gsub ESC_R_SB, R_SB
-    end unless str.empty?
-    str
+      if attributes
+        if format_mark == '`' && !old_behavior
+          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
+          # honor the escape of the attributes
+          preceding = %([#{attributes}])
+          attributes = nil
+        else
+          attributes = parse_quoted_text_attributes attributes
+        end
+      elsif format_mark == '`' && !old_behavior
+        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
+
+      if compat_mode
+        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)
+          passthrus[passthru_key = passthrus.size] = { text: content, subs: subs, attributes: attributes, type: :monospaced }
+        else
+          passthrus[passthru_key = passthrus.size] = { text: content, subs: BASIC_SUBS, attributes: attributes, type: :unquoted }
+        end
+      else
+        passthrus[passthru_key = passthrus.size] = { text: content, subs: BASIC_SUBS }
+      end
+
+      %(#{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 do
+      # honor the escape
+      next $&.slice 1, $&.length if $&.start_with? RS
+
+      if (type = $1.to_sym) == :stem
+        type = STEM_TYPE_ALIASES[@document.attributes['stem']].to_sym
+      end
+      content = normalize_text $3, nil, true
+      # NOTE drop enclosing $ signs around latexmath for backwards compatibility with AsciiDoc Python
+      content = content.slice 1, content.length - 2 if type == :latexmath && (content.start_with? '$') && (content.end_with? '$')
+      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
   end
 
-  # Internal: Split text formatted as CSV with support
-  # for double-quoted values (in which commas are ignored)
-  def split_simple_csv str
-    if str.empty?
-      []
-    elsif str.include? '"'
-      values = []
-      accum = ''
-      quote_open = false
-      str.each_char do |c|
-        case c
-        when ','
-          if quote_open
-            accum = accum + c
-          else
-            values << accum.strip
-            accum = ''
+  # Public: Restore the passthrough text by reinserting into the placeholder positions
+  #
+  # text  - The String text into which to restore the passthrough text
+  #
+  # returns The String text with the passthrough text restored
+  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])
+          if (attributes = pass[:attributes])
+            id = attributes['id']
           end
-        when '"'
-          quote_open = !quote_open
-        else
-          accum = accum + c
+          subbed_text = Inline.new(self, :quoted, subbed_text, type: type, id: id, attributes: attributes).convert
         end
+        subbed_text.include?(PASS_START) ? restore_passthroughs(subbed_text) : subbed_text
+      else
+        logger.error %(unresolved passthrough detected: #{text})
+        '??pass??'
       end
-      values << accum.strip
-    else
-      str.split(',').map {|it| it.strip }
     end
   end
 
-  # Internal: Resolve the list of comma-delimited subs against the possible options.
+  # Public: Resolve the list of comma-delimited subs against the possible options.
   #
-  # subs - A comma-delimited String of substitution aliases
+  # subs     - The comma-delimited String of substitution names or aliases.
+  # type     - A Symbol representing the context for which the subs are being resolved (default: :block).
+  # defaults - An Array of substitutions to start with when computing incremental substitutions (default: nil).
+  # subject  - The String to use in log messages to communicate the subject for which subs are being resolved (default: nil)
   #
-  # returns An Array of Symbols representing the substitution operation or nothing if no subs are found.
+  # Returns An Array of Symbols representing the substitution operation or nothing if no subs are found.
   def resolve_subs subs, type = :block, defaults = nil, subject = nil
     return if subs.nil_or_empty?
     # QUESTION should we store candidates as a Set instead of an Array?
@@ -1315,68 +1196,125 @@ module Substitutors
           candidates -= resolved_keys
         end
       else
-        candidates ||= []
-        candidates += resolved_keys
+        candidates ||= []
+        candidates += resolved_keys
+      end
+    end
+    return unless candidates
+    # weed out invalid options and remove duplicates (order is preserved; first occurence wins)
+    resolved = candidates & SUB_OPTIONS[type]
+    unless (candidates - resolved).empty?
+      invalid = candidates - resolved
+      logger.warn %(invalid substitution type#{invalid.size > 1 ? 's' : ''}#{subject ? ' for ' : ''}#{subject}: #{invalid.join ', '})
+    end
+    resolved
+  end
+
+  # Public: Call resolve_subs for the :block type.
+  def resolve_block_subs subs, defaults, subject
+    resolve_subs subs, :block, defaults, subject
+  end
+
+  # Public: Call resolve_subs for the :inline type with the subject set as passthrough macro.
+  def resolve_pass_subs subs
+    resolve_subs subs, :inline, nil, 'passthrough macro'
+  end
+
+  # Public: Expand all groups in the subs list and return. If no subs are resolve, return nil.
+  #
+  # subs - The substitutions to expand; can be a Symbol, Symbol Array or nil
+  #
+  # Returns a Symbol Array of substitutions to pass to apply_subs or nil if no substitutions were resolved.
+  def expand_subs subs
+    if ::Symbol === subs
+      unless subs == :none
+        SUB_GROUPS[subs] || [subs]
+      end
+    else
+      expanded_subs = []
+      subs.each do |key|
+        unless key == :none
+          if (sub_group = SUB_GROUPS[key])
+            expanded_subs += sub_group
+          else
+            expanded_subs << key
+          end
+        end
+      end
+
+      expanded_subs.empty? ? nil : expanded_subs
+    end
+  end
+
+  # Internal: Commit the requested substitutions to this block.
+  #
+  # Looks for an attribute named "subs". If present, resolves substitutions
+  # from the value of that attribute and assigns them to the subs property on
+  # this block. Otherwise, uses the substitutions assigned to the default_subs
+  # property, if specified, or selects a default set of substitutions based on
+  # the content model of the block.
+  #
+  # Returns nothing
+  def commit_subs
+    unless (default_subs = @default_subs)
+      case @content_model
+      when :simple
+        default_subs = NORMAL_SUBS
+      when :verbatim
+        # 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 : NO_SUBS
+      else
+        return @subs
       end
     end
-    return unless candidates
-    # weed out invalid options and remove duplicates (order is preserved; first occurence wins)
-    resolved = candidates & SUB_OPTIONS[type]
-    unless (candidates - resolved).empty?
-      invalid = candidates - resolved
-      logger.warn %(invalid substitution type#{invalid.size > 1 ? 's' : ''}#{subject ? ' for ' : ''}#{subject}: #{invalid.join ', '})
+
+    if (custom_subs = @attributes['subs'])
+      @subs = (resolve_block_subs custom_subs, default_subs, @context) || []
+    else
+      @subs = default_subs.drop 0
     end
-    resolved
-  end
 
-  def resolve_block_subs subs, defaults, subject
-    resolve_subs subs, :block, defaults, subject
-  end
+    # QUESION delegate this logic to a method?
+    if @context == :listing && @style == 'source' && (syntax_hl = @document.syntax_highlighter) &&
+        syntax_hl.highlight? && (idx = @subs.index :specialcharacters)
+      @subs[idx] = :highlight
+    end
 
-  def resolve_pass_subs subs
-    resolve_subs subs, :inline, nil, 'passthrough macro'
+    nil
   end
 
-  # 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.
-  #
-  # 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.
+  # Internal: Parse attributes in name or name=value format from a comma-separated String
   #
-  # source - the source code String to syntax highlight
-  # process_callouts - a Boolean flag indicating whether callout marks should be located and substituted
+  # attrlist - A comma-separated String list of attributes in name or name=value format.
+  # posattrs - An Array of positional attribute names (default: []).
+  # opts     - A Hash of options to control how the string is parsed (default: {}):
+  #            :into           - The Hash to parse the attributes into (optional, default: false).
+  #            :sub_input      - A Boolean that indicates whether to substitute attributes prior to
+  #                              parsing (optional, default: false).
+  #            :sub_result     - A Boolean that indicates whether to apply substitutions
+  #                              single-quoted attribute values (optional, default: true).
+  #            :unescape_input - A Boolean that indicates whether to unescape square brackets prior
+  #                              to parsing (optional, default: false).
   #
-  # 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?
-
-    source, callout_marks = extract_callouts source if process_callouts
-
-    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
+  # Returns an empty Hash if attrlist is nil or empty, otherwise a Hash of parsed attributes.
+  def parse_attributes attrlist, posattrs = [], opts = {}
+    return {} if attrlist ? attrlist.empty? : true
+    attrlist = normalize_text attrlist, true, true 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])
+      AttributeList.new(attrlist, block).parse_into(into, posattrs)
+    else
+      AttributeList.new(attrlist, block).parse(posattrs)
     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
-    highlighted = highlighted.gsub HighlightedPassSlotRx, %(#{PASS_START}\\1#{PASS_END}) unless @passthroughs.empty?
-
-    # NOTE highlight method may have depleted callouts
-    callout_marks.nil_or_empty? ? highlighted : (restore_callouts highlighted, callout_marks, source_offset)
   end
 
+  private
+
   # Internal: Extract the callout numbers from the source to prepare it for syntax highlighting.
   def extract_callouts source
     callout_marks = {}
@@ -1431,87 +1369,161 @@ module Substitutors
     end.join LF)
   end
 
-  # e.g., highlight="1-5, !2, 10" or highlight=1-5;!2,10
-  def resolve_lines_to_highlight source, spec
-    lines = []
-    spec = spec.delete ' ' if spec.include? ' '
-    ((spec.include? ',') ? (spec.split ',') : (spec.split ';')).map do |entry|
-      negate = false
-      if entry.start_with? '!'
-        entry = entry.slice 1, entry.length
-        negate = true
+  # 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[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
-      if (delim = (entry.include? '..') ? '..' : ((entry.include? '-') ? '-' : nil))
-        from, delim, to = entry.partition delim
-        to = (source.count LF) + 1 if to.empty? || (to = to.to_i) < 0
-        line_nums = (from.to_i..to).to_a
-        if negate
-          lines -= line_nums
-        else
-          lines.concat line_nums
-        end
+    else
+      %(#{pre}`#{text}`)
+    end
+  end
+
+  # Internal: Convert a quoted text region
+  #
+  # match  - The MatchData for the quoted text region
+  # type   - The quoting type (single, double, strong, emphasis, monospaced, etc)
+  # scope  - The scope of the quoting (constrained or unconstrained)
+  #
+  # Returns The converted String text for the quoted text region
+  def convert_quoted_text match, type, scope
+    if match[0].start_with? RS
+      if scope == :constrained && (attrs = match[2])
+        unescaped_attrs = %([#{attrs}])
       else
-        if negate
-          lines.delete entry.to_i
-        else
-          lines << entry.to_i
+        return match[0].slice 1, match[0].length
+      end
+    end
+
+    if scope == :constrained
+      if unescaped_attrs
+        %(#{unescaped_attrs}#{Inline.new(self, :quoted, match[3], type: type).convert})
+      else
+        if (attrlist = match[2])
+          id = (attributes = parse_quoted_text_attributes attrlist)['id']
+          type = :unquoted if type == :mark
         end
+        %(#{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)['id']
+        type = :unquoted if type == :mark
       end
+      Inline.new(self, :quoted, match[2], type: type, id: id, attributes: attributes).convert
     end
-    lines.sort.uniq
   end
 
-  # Public: Apply verbatim substitutions on source (for use when highlighting is disabled).
-  #
-  # source - the source code String on which to apply verbatim substitutions
-  # process_callouts - a Boolean flag indicating whether callout marks should be substituted
+  # Internal: Substitute replacement text for matched location
   #
-  # returns the substituted source
-  def sub_source source, process_callouts
-    process_callouts ? sub_callouts(sub_specialchars source) : (sub_specialchars source)
+  # returns The String text with the replacement characters substituted
+  def do_replacement m, replacement, restore
+    if (captured = m[0]).include? RS
+      # we have to use sub since we aren't sure it's the first char
+      captured.sub RS, ''
+    else
+      case restore
+      when :none
+        replacement
+      when :bounding
+        m[1] + replacement + m[2]
+      else # :leading
+        m[1] + replacement
+      end
+    end
   end
 
   # Internal: Inserts text into a formatted text enclosure; used by xreftext
   alias sub_placeholder sprintf unless RUBY_ENGINE == 'opal'
 
-  # Internal: Commit the requested substitutions to this block.
+  # Internal: Parse the attributes that are defined on quoted (aka formatted) text
   #
-  # Looks for an attribute named "subs". If present, resolves substitutions
-  # from the value of that attribute and assigns them to the subs property on
-  # this block. Otherwise, uses the substitutions assigned to the default_subs
-  # property, if specified, or selects a default set of substitutions based on
-  # the content model of the block.
+  # str - A non-nil String of unprocessed attributes;
+  #       space-separated roles (e.g., role1 role2) or the id/role shorthand syntax (e.g., #idname.role)
   #
-  # Returns The Array of resolved substitutions now assigned to this block
-  def commit_subs
-    unless (default_subs = @default_subs)
-      case @content_model
-      when :simple
-        default_subs = NORMAL_SUBS
-      when :verbatim
-        # 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 : NO_SUBS
+  # 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 (very unlikely)
+    str = str.slice 0, (str.index ',') if str.include? ','
+
+    if (str.start_with? '.', '#') && Compliance.shorthand_property_syntax
+      segments = str.split '#', 2
+
+      if segments.size > 1
+        id, *more_roles = segments[1].split('.')
       else
-        return @subs
+        more_roles = []
       end
-    end
 
-    if (custom_subs = @attributes['subs'])
-      @subs = (resolve_block_subs custom_subs, default_subs, @context) || []
+      roles = segments[0].empty? ? [] : segments[0].split('.')
+      if roles.size > 1
+        roles.shift
+      end
+
+      if more_roles.size > 0
+        roles.concat more_roles
+      end
+
+      attrs = {}
+      attrs['id'] = id if id
+      attrs['role'] = roles.join ' ' unless roles.empty?
+      attrs
     else
-      @subs = default_subs.drop 0
+      { 'role' => str }
     end
+  end
 
-    # QUESION delegate this logic to a method?
-    if @context == :listing && @style == 'source' && (syntax_hl = @document.syntax_highlighter) &&
-        syntax_hl.highlight? && (idx = @subs.index :specialcharacters)
-      @subs[idx] = :highlight
+  # Internal: Normalize text to prepare it for parsing.
+  #
+  # If normalize_whitespace is true, strip surrounding whitespace and fold newlines. If unescape_closing_square_bracket
+  # is set, unescape any escaped closing square brackets.
+  #
+  # Returns the normalized text String
+  def normalize_text text, normalize_whitespace = nil, unescape_closing_square_brackets = nil
+    unless text.empty?
+      text = text.strip.tr LF, ' ' if normalize_whitespace
+      text = text.gsub ESC_R_SB, R_SB if unescape_closing_square_brackets && (text.include? R_SB)
     end
+    text
+  end
 
-    @subs
+  # Internal: Split text formatted as CSV with support
+  # for double-quoted values (in which commas are ignored)
+  def split_simple_csv str
+    if str.empty?
+      []
+    elsif str.include? '"'
+      values = []
+      accum = ''
+      quote_open = nil
+      str.each_char do |c|
+        case c
+        when ','
+          if quote_open
+            accum = accum + c
+          else
+            values << accum.strip
+            accum = ''
+          end
+        when '"'
+          quote_open = !quote_open
+        else
+          accum = accum + c
+        end
+      end
+      values << accum.strip
+    else
+      str.split(',').map {|it| it.strip }
+    end
   end
 end
 end