asciidoctor 2.0.10 → 2.0.15

data/lib/asciidoctor.rb

@@ -136,8 +136,8 @@ module Asciidoctor
     # Compliance value: true
     define :underline_style_section_titles, true
 
-    # Asciidoctor will unwrap the content in a preamble
-    # if the document has a title and no sections.
+    # Asciidoctor will unwrap the content in a preamble if the document has a
+    # title and no sections, then discard the empty preamble.
     # Compliance value: false
     define :unwrap_standalone_preamble, true
 
@@ -148,7 +148,7 @@ module Asciidoctor
     # Compliance value: 'drop-line'
     define :attribute_missing, 'skip'
 
-    # AsciiDoc drops lines that contain an attribute unassignemnt.
+    # AsciiDoc drops lines that contain an attribute unassignment.
     # This behavior may need to be tuned depending on the circumstances.
     # Compliance value: 'drop-line'
     define :attribute_undefined, 'drop-line'
@@ -296,7 +296,7 @@ module Asciidoctor
   DELIMITED_BLOCK_TAILS = {}.tap {|accum| DELIMITED_BLOCKS.each_key {|k| accum[k] = k[k.length - 1] if k.length == 4 } }
 
   # NOTE the 'figure' key as a string is historical and used by image blocks
-  CAPTION_ATTR_NAMES = { example: 'example-caption', 'figure' => 'figure-caption', listing: 'listing-caption', table: 'table-caption' }
+  CAPTION_ATTRIBUTE_NAMES = { example: 'example-caption', 'figure' => 'figure-caption', listing: 'listing-caption', table: 'table-caption' }
 
   LAYOUT_BREAK_CHARS = {
     '\'' => :thematic_break,
@@ -332,7 +332,7 @@ module Asciidoctor
 
   LIST_CONTINUATION = '+'
 
-  # NOTE AsciiDoc Python allows + to be preceded by TAB; Asciidoctor does not
+  # NOTE AsciiDoc.py allows + to be preceded by TAB; Asciidoctor does not
   HARD_LINE_BREAK = ' +'
 
   LINE_CONTINUATION = ' \\'
@@ -357,9 +357,35 @@ module Asciidoctor
 
   FONT_AWESOME_VERSION = '4.7.0'
 
-  HIGHLIGHT_JS_VERSION = '9.15.6'
-
-  MATHJAX_VERSION = '2.7.5'
+  HIGHLIGHT_JS_VERSION = '9.18.3'
+
+  MATHJAX_VERSION = '2.7.9'
+
+  DEFAULT_ATTRIBUTES = {
+    'appendix-caption' => 'Appendix',
+    'appendix-refsig' => 'Appendix',
+    'caution-caption' => 'Caution',
+    'chapter-refsig' => 'Chapter',
+    #'encoding' => 'UTF-8',
+    'example-caption' => 'Example',
+    'figure-caption' => 'Figure',
+    'important-caption' => 'Important',
+    'last-update-label' => 'Last updated',
+    #'listing-caption' => 'Listing',
+    'note-caption' => 'Note',
+    'part-refsig' => 'Part',
+    #'preface-title' => 'Preface',
+    'prewrap' => '',
+    'sectids' => '',
+    'section-refsig' => 'Section',
+    'table-caption' => 'Table',
+    'tip-caption' => 'Tip',
+    'toc-placement' => 'auto',
+    'toc-title' => 'Table of Contents',
+    'untitled-label' => 'Untitled',
+    'version-label' => 'Version',
+    'warning-caption' => 'Warning',
+  }
 
   # attributes which be changed throughout the flow of the document (e.g., sectnums)
   FLEXIBLE_ATTRIBUTES = ['sectnums']
@@ -433,9 +459,9 @@ module Asciidoctor
       [:emphasis, :unconstrained, /\\?(?:\[([^\]]+)\])?__(#{CC_ALL}+?)__/m],
       # _emphasis_
       [:emphasis, :constrained, /(^|[^#{CC_WORD};:}])(?:\[([^\]]+)\])?_(\S|\S#{CC_ALL}*?\S)_(?!#{CG_WORD})/m],
-      # ##mark## (referred to in AsciiDoc Python as unquoted)
+      # ##mark## (referred to in AsciiDoc.py as unquoted)
       [:mark, :unconstrained, /\\?(?:\[([^\]]+)\])?##(#{CC_ALL}+?)##/m],
-      # #mark# (referred to in AsciiDoc Python as unquoted)
+      # #mark# (referred to in AsciiDoc.py as unquoted)
       [:mark, :constrained, /(^|[^#{CC_WORD}&;:}])(?:\[([^\]]+)\])?#(\S|\S#{CC_ALL}*?\S)#(?!#{CG_WORD})/m],
       # ^superscript^
       [:superscript, :unconstrained, /\\?(?:\[([^\]]+)\])?\^(\S+?)\^/],
@@ -511,8 +537,8 @@ module Asciidoctor
   end unless RUBY_ENGINE == 'opal'
 
   unless RUBY_ENGINE == 'opal'
-    autoload :SyntaxHighlighter, %(#{LIB_DIR}/asciidoctor/syntax_highlighter)
-    autoload :Timings, %(#{LIB_DIR}/asciidoctor/timings)
+    autoload :SyntaxHighlighter, %(#{__dir__}/asciidoctor/syntax_highlighter)
+    autoload :Timings, %(#{__dir__}/asciidoctor/timings)
   end
 end
 

data/lib/asciidoctor/abstract_block.rb

@@ -141,6 +141,11 @@ class AbstractBlock < AbstractNode
     (Integer @numeral) rescue @numeral
   end
 
+  # Deprecated: Legacy property to set the numeral of this section by coercing the value to a String.
+  def number= val
+    @numeral = val.to_s
+  end
+
   # Public: Walk the document tree and find all block-level nodes that match the specified selector (context, style, id,
   # role, and/or custom filter).
   #
@@ -338,17 +343,17 @@ class AbstractBlock < AbstractNode
     if (val = reftext) && !val.empty?
       val
     # NOTE xrefstyle only applies to blocks with a title and a caption or number
-    elsif xrefstyle && @title && @caption
+    elsif xrefstyle && @title && !@caption.nil_or_empty?
       case xrefstyle
       when 'full'
         quoted_title = sub_placeholder (sub_quotes @document.compat_mode ? %q(``%s'') : '"`%s`"'), title
-        if @numeral && (caption_attr_name = CAPTION_ATTR_NAMES[@context]) && (prefix = @document.attributes[caption_attr_name])
+        if @numeral && (caption_attr_name = CAPTION_ATTRIBUTE_NAMES[@context]) && (prefix = @document.attributes[caption_attr_name])
           %(#{prefix} #{@numeral}, #{quoted_title})
         else
           %(#{@caption.chomp '. '}, #{quoted_title})
         end
       when 'short'
-        if @numeral && (caption_attr_name = CAPTION_ATTR_NAMES[@context]) && (prefix = @document.attributes[caption_attr_name])
+        if @numeral && (caption_attr_name = CAPTION_ATTRIBUTE_NAMES[@context]) && (prefix = @document.attributes[caption_attr_name])
           %(#{prefix} #{@numeral})
         else
           @caption.chomp '. '
@@ -380,7 +385,7 @@ class AbstractBlock < AbstractNode
   # Returns nothing.
   def assign_caption value, caption_context = @context
     unless @caption || !@title || (@caption = value || @document.attributes['caption'])
-      if (attr_name = CAPTION_ATTR_NAMES[caption_context]) && (prefix = @document.attributes[attr_name])
+      if (attr_name = CAPTION_ATTRIBUTE_NAMES[caption_context]) && (prefix = @document.attributes[attr_name])
         @caption = %(#{prefix} #{@numeral = @document.increment_and_store_counter %(#{caption_context}-number), self}. )
         nil
       end

data/lib/asciidoctor/abstract_node.rb

@@ -65,7 +65,7 @@ class AbstractNode
   #
   # parent - The Block to set as the parent of this Block
   #
-  # Returns the new parent Block associated with this Block
+  # Returns the value of the parent argument
   def parent= parent
     @parent, @document = parent, parent.document
   end
@@ -216,6 +216,15 @@ class AbstractNode
     (val = @attributes['role']) ? (%( #{val} ).include? %( #{name} )) : false
   end
 
+  # Public: Sets the value of the role attribute on this node.
+  #
+  # names - A single role name, a space-separated String of role names, or an Array of role names
+  #
+  # Returns the value of the names argument
+  def role= names
+    @attributes['role'] = (::Array === names) ? (names.join ' ') : names
+  end
+
   # Public: Adds the given role directly to this node.
   #
   # Returns a [Boolean] indicating whether the role was added.
@@ -514,6 +523,7 @@ class AbstractNode
   #          * :normalize a Boolean that indicates whether the data should be normalized (default: false)
   #          * :start the String relative base path to use when resolving the target (default: nil)
   #          * :warn_on_failure a Boolean that indicates whether warnings are issued if the target cannot be read (default: true)
+  #          * :warn_if_empty a Boolean that indicates whether a warning is issued if contents of target is empty (default: false)
   # Returns the contents of the resolved target or nil if the resolved target cannot be read
   # --
   # TODO refactor other methods in this class to use this method were possible (repurposing if necessary)
@@ -525,22 +535,22 @@ class AbstractNode
         Helpers.require_library 'open-uri/cached', 'open-uri-cached' if doc.attr? 'cache-uri'
         begin
           if opts[:normalize]
-            (Helpers.prepare_source_string ::OpenURI.open_uri(target, URI_READ_MODE) {|f| f.read }).join LF
+            contents = (Helpers.prepare_source_string ::OpenURI.open_uri(target, URI_READ_MODE) {|f| f.read }).join LF
           else
-            ::OpenURI.open_uri(target, URI_READ_MODE) {|f| f.read }
+            contents = ::OpenURI.open_uri(target, URI_READ_MODE) {|f| f.read }
           end
         rescue
           logger.warn %(could not retrieve contents of #{opts[:label] || 'asset'} at URI: #{target}) if opts.fetch :warn_on_failure, true
-          return
         end
       else
         logger.warn %(cannot retrieve contents of #{opts[:label] || 'asset'} at URI: #{target} (allow-uri-read attribute not enabled)) if opts.fetch :warn_on_failure, true
-        return
       end
     else
       target = normalize_system_path target, opts[:start], nil, target_name: (opts[:label] || 'asset')
-      read_asset target, normalize: opts[:normalize], warn_on_failure: (opts.fetch :warn_on_failure, true), label: opts[:label]
+      contents = read_asset target, normalize: opts[:normalize], warn_on_failure: (opts.fetch :warn_on_failure, true), label: opts[:label]
     end
+    logger.warn %(contents of #{opts[:label] || 'asset'} is empty: #{target}) if contents && opts[:warn_if_empty] && contents.empty?
+    contents
   end
 
   # Deprecated: Check whether the specified String is a URI by

data/lib/asciidoctor/attribute_list.rb

@@ -22,19 +22,20 @@ module Asciidoctor
 #    => { 'style' => 'quote', 'attribution' => 'Famous Person', 'citetitle' => 'Famous Book (2001)' }
 #
 class AttributeList
-  BACKSLASH = '\\'
   APOS = '\''
+  BACKSLASH = '\\'
+  QUOT = '"'
 
   # Public: Regular expressions for detecting the boundary of a value
-  BoundaryRxs = {
-    '"' => /.*?[^\\](?=")/,
+  BoundaryRx = {
+    QUOT => /.*?[^\\](?=")/,
     APOS => /.*?[^\\](?=')/,
     ',' => /.*?(?=[ \t]*(,|$))/
   }
 
   # Public: Regular expressions for unescaping quoted characters
   EscapedQuotes = {
-    '"' => '\\"',
+    QUOT => '\\"',
     APOS => '\\\''
   }
 
@@ -45,14 +46,16 @@ class AttributeList
   BlankRx = /[ \t]+/
 
   # Public: Regular expressions for skipping delimiters
-  SkipRxs = { ',' => /[ \t]*(,|$)/ }
+  SkipRx = {
+    ',' => /[ \t]*(,|$)/
+  }
 
   def initialize source, block = nil, delimiter = ','
     @scanner = ::StringScanner.new source
     @block = block
     @delimiter = delimiter
-    @delimiter_skip_pattern = SkipRxs[delimiter]
-    @delimiter_boundary_pattern = BoundaryRxs[delimiter]
+    @delimiter_skip_pattern = SkipRx[delimiter]
+    @delimiter_boundary_pattern = BoundaryRx[delimiter]
     @attributes = nil
   end
 
@@ -65,8 +68,6 @@ class AttributeList
     return @attributes if @attributes
 
     @attributes = {}
-    # QUESTION do we want to store the attribute list as the zero-index attribute?
-    #attributes[0] = @scanner.string
     index = 0
 
     while parse_attribute index, positional_attrs
@@ -83,75 +84,73 @@ class AttributeList
   end
 
   def self.rekey attributes, positional_attrs
-    index = 0
-    positional_attrs.each do |key|
-      index += 1
-      if (val = attributes[index])
+    positional_attrs.each_with_index do |key, index|
+      if key && (val = attributes[index + 1])
         # QUESTION should we delete the positional key?
         attributes[key] = val
-      end if key
+      end
     end
     attributes
   end
 
   private
 
-  def parse_attribute index = 0, positional_attrs = []
-    single_quoted_value = false
+  def parse_attribute index, positional_attrs
+    continue = true
     skip_blank
-    # example: "quote"
-    if (first = @scanner.peek(1)) == '"'
+    case @scanner.peek 1
+    # example: "quote" || "foo
+    when QUOT
       name = parse_attribute_value @scanner.get_byte
-      value = nil
-    # example: 'quote'
-    elsif first == APOS
+    # example: 'quote' || 'foo
+    when APOS
       name = parse_attribute_value @scanner.get_byte
-      value = nil
-      single_quoted_value = true unless name.start_with? APOS
+      single_quoted = true unless name.start_with? APOS
     else
-      name = scan_name
-
-      skipped = 0
-      c = nil
+      skipped = ((name = scan_name) && skip_blank) || 0
       if @scanner.eos?
-        return false unless name
-      else
-        skipped = skip_blank || 0
-        c = @scanner.get_byte
-      end
-
-      # example: quote
-      if !c || c == @delimiter
-        value = nil
-      # example: Sherlock Holmes || =foo=
-      elsif c != '=' || !name
-        name = %(#{name}#{' ' * skipped}#{c}#{scan_to_delimiter})
-        value = nil
-      else
-        skip_blank
-        if @scanner.peek(1)
-          # example: foo="bar" || foo="ba\"zaar"
-          if (c = @scanner.get_byte) == '"'
+        return unless name || (@scanner.string.rstrip.end_with? @delimiter)
+        # example: quote (at eos)
+        continue = nil
+      # example: quote,
+      elsif (c = @scanner.get_byte) == @delimiter
+        @scanner.unscan
+      elsif name
+        # example: foo=...
+        if c == '='
+          skip_blank
+          case (c = @scanner.get_byte)
+          # example: foo="bar" || foo="ba\"zaar" || foo="bar
+          when QUOT
             value = parse_attribute_value c
-          # example: foo='bar' || foo='ba\'zaar' || foo='ba"zaar'
-          elsif c == APOS
+          # example: foo='bar' || foo='ba\'zaar' || foo='ba"zaar' || foo='bar
+          when APOS
             value = parse_attribute_value c
-            single_quoted_value = true unless value.start_with? APOS
+            single_quoted = true unless value.start_with? APOS
           # example: foo=,
-          elsif c == @delimiter
+          when @delimiter
+            value = ''
+            @scanner.unscan
+          # example: foo= (at eos)
+          when nil
             value = ''
-          # example: foo=bar (all spaces ignored)
+          # example: foo=bar || foo=None
           else
             value = %(#{c}#{scan_to_delimiter})
             return true if value == 'None'
           end
+        # example: foo bar
+        else
+          name = %(#{name}#{' ' * skipped}#{c}#{scan_to_delimiter})
         end
+      # example: =foo= || !foo
+      else
+        name = %(#{c}#{scan_to_delimiter})
       end
     end
 
     if value
-      # example: options="opt1,opt2,opt3"
-      # opts is an alias for options
+      # example: options="opt1,opt2,opt3" || opts="opts1,opt2,opt3"
       case name
       when 'options', 'opts'
         if value.include? ','
@@ -161,7 +160,7 @@ class AttributeList
           @attributes[%(#{value}-option)] = '' unless value.empty?
         end
       else
-        if single_quoted_value && @block
+        if single_quoted && @block
           case name
           when 'title', 'reftext'
             @attributes[name] = value
@@ -173,33 +172,26 @@ class AttributeList
         end
       end
     else
-      resolved_name = single_quoted_value && @block ? (@block.apply_subs name) : name
-      if (positional_attr_name = positional_attrs[index])
-        @attributes[positional_attr_name] = resolved_name
+      name = @block.apply_subs name if single_quoted && @block
+      if (positional_attr_name = positional_attrs[index]) && name
+        @attributes[positional_attr_name] = name
       end
-      # QUESTION should we always assign the positional key?
-      @attributes[index + 1] = resolved_name
-      # QUESTION should we assign the resolved name as an attribute?
-      #@attributes[resolved_name] = nil
+      # QUESTION should we assign the positional key even when it's claimed by a positional attribute?
+      @attributes[index + 1] = name
     end
 
-    true
+    continue
   end
 
   def parse_attribute_value quote
     # empty quoted value
-    if @scanner.peek(1) == quote
+    if (@scanner.peek 1) == quote
       @scanner.get_byte
-      return ''
-    end
-
-    if (value = scan_to_quote quote)
+      ''
+    elsif (value = scan_to_quote quote)
       @scanner.get_byte
-      if value.include? BACKSLASH
-        value.gsub EscapedQuotes[quote], quote
-      else
-        value
-      end
+      (value.include? BACKSLASH) ? (value.gsub EscapedQuotes[quote], quote) : value
+    # leading quote only
     else
       %(#{quote}#{scan_to_delimiter})
     end
@@ -222,7 +214,7 @@ class AttributeList
   end
 
   def scan_to_quote quote
-    @scanner.scan BoundaryRxs[quote]
+    @scanner.scan BoundaryRx[quote]
   end
 end
 end

data/lib/asciidoctor/cli/invoker.rb

@@ -42,6 +42,8 @@ module Asciidoctor
         non_posix_env = ::File::ALT_SEPARATOR == RS
         err = @err || $stderr
         show_timings = false
+        # NOTE in Ruby 2.7, RubyGems sets SOURCE_DATE_EPOCH if it's not set
+        ::ENV.delete 'SOURCE_DATE_EPOCH' if (::ENV.key? 'IGNORE_SOURCE_DATE_EPOCH') && (::Gem.respond_to? :source_date_epoch)
 
         @options.map do |key, val|
           case key

data/lib/asciidoctor/cli/options.rb

@@ -39,14 +39,15 @@ module Asciidoctor
           # NOTE don't use squiggly heredoc to maintain compatibility with Ruby < 2.3
           opts.banner = <<-'EOS'.gsub '          ', ''
           Usage: asciidoctor [OPTION]... FILE...
-          Translate the AsciiDoc source FILE or FILE(s) into the backend output format (e.g., HTML 5, DocBook 5, etc.)
-          By default, the output is written to a file with the basename of the source file and the appropriate extension.
-          Example: asciidoctor -b html5 source.asciidoc
+          Convert the AsciiDoc input FILE(s) to the backend output format (e.g., HTML 5, DocBook 5, etc.)
+          Unless specified otherwise, the output is written to a file whose name is derived from the input file.
+          Application log messages are printed to STDERR.
+          Example: asciidoctor input.adoc
 
           EOS
 
-          opts.on('-b', '--backend BACKEND', 'set output format backend: [html5, xhtml5, docbook5, manpage] (default: html5)',
-                  'additional backends are supported via extensions (e.g., pdf, latex)') do |backend|
+          opts.on('-b', '--backend BACKEND', 'set backend output format: [html5, xhtml5, docbook5, manpage] (default: html5)',
+                  'additional backends are supported via extended converters (e.g., pdf, epub3)') do |backend|
             self[:attributes]['backend'] = backend
           end
           opts.on('-d', '--doctype DOCTYPE', ['article', 'book', 'manpage', 'inline'],
@@ -76,8 +77,8 @@ module Asciidoctor
           opts.on('-n', '--section-numbers', 'auto-number section titles in the HTML backend; disabled by default') do
             self[:attributes]['sectnums'] = ''
           end
-          opts.on('--eruby ERUBY', ['erb', 'erubis'],
-                  'specify eRuby implementation to use when rendering custom ERB templates: [erb, erubis] (default: erb)') do |eruby|
+          opts.on('--eruby ERUBY', ['erb', 'erubi', 'erubis'],
+                  'specify eRuby implementation to use when rendering custom ERB templates: [erb, erubi, erubis] (default: erb)') do |eruby|
             self[:eruby] = eruby
           end
           opts.on('-a', '--attribute name[=value]', 'a document attribute to set in the form of name, name!, or name=value pair',
@@ -128,7 +129,7 @@ module Asciidoctor
           opts.on('--trace', 'include backtrace information when reporting errors (default: false)') do |trace|
             self[:trace] = true
           end
-          opts.on('-v', '--verbose', 'enable verbose mode (default: false)') do |verbose|
+          opts.on('-v', '--verbose', 'directs application messages logged at DEBUG or INFO level to STDERR (default: false)') do |verbose|
             self[:verbose] = 2
           end
           opts.on('-w', '--warnings', 'turn on script warnings (default: false)') do |warnings|
@@ -205,7 +206,7 @@ module Asciidoctor
         # shave off the file to process so that options errors appear correctly
         if args.size == 1 && args[0] == '-'
           infiles << args.pop
-        elsif
+        else
           args.each do |file|
             if file.start_with? '-'
               # warn, but don't panic; we may have enough to proceed, so we won't force a failure