asciidoctor 2.0.10 → 2.0.17

data/lib/asciidoctor/abstract_block.rb

@@ -11,7 +11,7 @@ class AbstractBlock < AbstractNode
   # * :compound - this block contains other blocks
   # * :simple - this block holds a paragraph of prose that receives normal substitutions
   # * :verbatim - this block holds verbatim text (displayed "as is") that receives verbatim substitutions
-  # * :raw - this block holds unprocessed content passed directly to the output with no sustitutions applied
+  # * :raw - this block holds unprocessed content passed directly to the output with no substitutions applied
   # * :empty - this block has no content
   attr_accessor :content_model
 
@@ -90,7 +90,7 @@ class AbstractBlock < AbstractNode
   #
   # context - the context Symbol context to assign to this block
   #
-  # Returns the new context Symbol assigned to this block
+  # Returns the specified Symbol context
   def context= context
     @node_name = (@context = context).to_s
   end
@@ -129,11 +129,13 @@ class AbstractBlock < AbstractNode
 
   # Public: Check whether this block has any child Section objects.
   #
-  # Only applies to Document and Section instances
+  # Acts an an abstract method that always returns false unless this block is an
+  # instance of Document or Section.
+  # Both Document and Section provide overrides for this method.
   #
-  # Returns A [Boolean] to indicate whether this block has child Section objects
+  # Returns false
   def sections?
-    @next_section_index > 0
+    false
   end
 
   # Deprecated: Legacy property to get the String or Integer numeral of this section.
@@ -141,6 +143,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).
   #
@@ -264,7 +271,7 @@ class AbstractBlock < AbstractNode
     ORDERED_LIST_KEYWORDS[list_type || @style]
   end
 
-  # Public: Get the String title of this Block with title substitions applied
+  # Public: Get the String title of this Block with title substitutions applied
   #
   # The following substitutions are applied to block and section titles:
   #
@@ -291,7 +298,7 @@ class AbstractBlock < AbstractNode
 
   # Public: Set the String block title.
   #
-  # Returns the new String title assigned to this Block
+  # Returns the specified String title
   def title= val
     @converted_title = nil
     @title = val
@@ -338,17 +345,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 +387,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
@@ -475,7 +482,7 @@ class AbstractBlock < AbstractNode
           @header.find_by_internal selector, result, &block
         end
         @blocks.each do |b|
-          next if (context_selector == :section && b.context != :section) # optimization
+          next if context_selector == :section && b.context != :section # optimization
           b.find_by_internal selector, result, &block
         end
       end
@@ -500,7 +507,7 @@ class AbstractBlock < AbstractNode
       end
     else
       @blocks.each do |b|
-        next if (context_selector == :section && b.context != :section) # optimization
+        next if context_selector == :section && b.context != :section # optimization
         b.find_by_internal selector, result, &block
       end
     end

data/lib/asciidoctor/abstract_node.rb

@@ -4,7 +4,8 @@ module Asciidoctor
 # node of AsciiDoc content. The state and methods on this class are common to
 # all content segments in an AsciiDoc document.
 class AbstractNode
-  include Substitutors, Logging
+  include Logging
+  include Substitutors
 
   # Public: Get the Hash of attributes for this node
   attr_reader :attributes
@@ -65,7 +66,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 the specified Block parent
   def parent= parent
     @parent, @document = parent, parent.document
   end
@@ -155,7 +156,7 @@ class AbstractNode
   #
   # name - the String name of the option
   #
-  # Returns Nothing
+  # Returns nothing
   def set_option name
     @attributes[%(#{name}-option)] = ''
     nil
@@ -216,6 +217,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 specified String role name or Array of role names
+  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.
@@ -453,8 +463,8 @@ class AbstractNode
         start = doc.base_dir
       end
     else
-      start = doc.base_dir unless start
-      jail = doc.base_dir unless jail
+      start ||= doc.base_dir
+      jail ||= doc.base_dir
     end
     doc.path_resolver.system_path target, start, jail, opts
   end
@@ -514,6 +524,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 +536,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
+      elsif opts.fetch :warn_on_failure, true
+        logger.warn %(cannot retrieve contents of #{opts[:label] || 'asset'} at URI: #{target} (allow-uri-read attribute not enabled))
       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/block.rb

@@ -54,21 +54,21 @@ class Block < AbstractBlock
       # FIXME feels funky; we have to be defensive to get commit_subs to honor override
       # FIXME does not resolve substitution groups inside Array (e.g., [:normal])
       if (subs = opts[:subs])
-        # e.g., subs: :defult
+        case subs
+        # e.g., subs: :default
         # subs attribute is honored; falls back to opts[:default_subs], then built-in defaults based on context
-        if subs == :default
+        when :default
           @default_subs = opts[:default_subs]
         # e.g., subs: [:quotes]
         # subs attribute is not honored
-        elsif ::Array === subs
+        when ::Array
           @default_subs = subs.drop 0
           @attributes.delete 'subs'
         # e.g., subs: :normal or subs: 'normal'
         # subs attribute is not honored
         else
           @default_subs = nil
-          # interpolation is the fastest way to dup subs as a string
-          @attributes['subs'] = %(#{subs})
+          @attributes['subs'] = subs.to_s
         end
         # resolve the subs eagerly only if subs option is specified
         # QUESTION should we skip subsequent calls to commit_subs?
@@ -123,7 +123,7 @@ class Block < AbstractBlock
         result.join LF
       end
     else
-      logger.warn %(Unknown content model '#{@content_model}' for block: #{to_s}) unless @content_model == :empty
+      logger.warn %(Unknown content model '#{@content_model}' for block: #{self}) unless @content_model == :empty
       nil
     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
@@ -86,7 +88,6 @@ module Asciidoctor
         end
 
         if outfile == '-'
-          # NOTE set_encoding returns nil on JRuby 9.1
           (tofile = @out) || ((tofile = $stdout).set_encoding UTF_8)
         elsif outfile
           opts[:mkdirs] = true
@@ -141,7 +142,7 @@ module Asciidoctor
             raise e
           else
             err.puts ::RuntimeError === e ? %(#{e.message} (#{e.class})) : e.message
-            err.puts '  Use --trace for backtrace'
+            err.puts '  Use --trace to show backtrace'
           end
         end
         nil

data/lib/asciidoctor/cli/options.rb

@@ -39,19 +39,20 @@ 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'],
-                  'document type to use when converting document: [article, book, manpage, inline] (default: article)') do |doc_type|
-            self[:attributes]['doctype'] = doc_type
+              'document type to use when converting document: [article, book, manpage, inline] (default: article)') do |doctype|
+            self[:attributes]['doctype'] = doctype
           end
           opts.on('-e', '--embedded', 'suppress enclosing document structure and output an embedded document (default: false)') do
             self[:standalone] = false
@@ -60,14 +61,14 @@ module Asciidoctor
             self[:output_file] = output_file
           end
           opts.on('--safe',
-                  'set safe mode level to safe (default: unsafe)',
-                  'enables include directives, but prevents access to ancestor paths of source file',
-                  'provided for compatibility with the asciidoc command') do
+              'set safe mode level to safe (default: unsafe)',
+              'enables include directives, but prevents access to ancestor paths of source file',
+              'provided for compatibility with the asciidoc command') do
             self[:safe] = SafeMode::SAFE
           end
           opts.on('-S', '--safe-mode SAFE_MODE', (safe_mode_names = SafeMode.names),
-                  %(set safe mode level explicitly: [#{safe_mode_names.join ', '}] (default: unsafe)),
-                  'disables potentially dangerous macros in source files, such as include::[]') do |name|
+              %(set safe mode level explicitly: [#{safe_mode_names.join ', '}] (default: unsafe)),
+              'disables potentially dangerous macros in source files, such as include::[]') do |name|
             self[:safe] = SafeMode.value_for_name name
           end
           opts.on('-s', '--no-header-footer', 'suppress enclosing document structure and output an embedded document (default: false)') do
@@ -76,20 +77,20 @@ 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',
-                  'this attribute takes precedence over the same attribute defined in the source document',
-                  'unless either the name or value ends in @ (i.e., name@=value or name=value@)') do |attr|
+              'this attribute takes precedence over the same attribute defined in the source document',
+              'unless either the name or value ends in @ (i.e., name@=value or name=value@)') do |attr|
             next if (attr = attr.rstrip).empty? || attr == '='
             attr = attr.encode UTF_8 unless attr.encoding == UTF_8
             name, _, val = attr.partition '='
             self[:attributes][name] = val
           end
           opts.on('-T', '--template-dir DIR', 'a directory containing custom converter templates that override the built-in converter (requires tilt gem)',
-                  'may be specified multiple times') do |template_dir|
+              'may be specified multiple times') do |template_dir|
             if self[:template_dirs].nil?
               self[:template_dirs] = [template_dir]
             elsif ::Array === self[:template_dirs]
@@ -118,23 +119,23 @@ module Asciidoctor
               'may be specified more than once') do |path|
             (self[:requires] ||= []).concat(path.split ',')
           end
-          opts.on('--failure-level LEVEL', %w(warning WARNING error ERROR info INFO), 'set minimum logging level that triggers non-zero exit code: [WARN, ERROR, INFO] (default: FATAL)') do |level|
+          opts.on('--failure-level LEVEL', %w(info INFO warning WARNING error ERROR fatal FATAL), 'set minimum log level that yields a non-zero exit code: [INFO, WARN, ERROR, FATAL] (default: FATAL)') do |level|
             level = 'WARN' if (level = level.upcase) == 'WARNING'
-            self[:failure_level] = ::Logger::Severity.const_get level, false
+            self[:failure_level] = ::Logger::Severity.const_get level
           end
-          opts.on('-q', '--quiet', 'silence application log messages and script warnings (default: false)') do |verbose|
+          opts.on('-q', '--quiet', 'silence application log messages and script warnings (default: false)') do
             self[:verbose] = 0
           end
-          opts.on('--trace', 'include backtrace information when reporting errors (default: false)') do |trace|
+          opts.on('--trace', 'include backtrace information when reporting errors (default: false)') do
             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
             self[:verbose] = 2
           end
-          opts.on('-w', '--warnings', 'turn on script warnings (default: false)') do |warnings|
+          opts.on('-w', '--warnings', 'turn on script warnings (default: false)') do
             self[:warnings] = true
           end
-          opts.on('-t', '--timings', 'print timings report (default: false)') do |timing|
+          opts.on('-t', '--timings', 'print timings report (default: false)') do
             self[:timings] = true
           end
           opts.on_tail('-h', '--help [TOPIC]', 'print a help message',
@@ -160,7 +161,7 @@ module Asciidoctor
               elsif ::File.exist? (manpage_path = (::File.join ROOT_DIR, 'man', 'asciidoctor.1'))
                 $stdout.puts ::File.read manpage_path
               else
-                manpage_path = `man -w asciidoctor`.chop rescue ''
+                manpage_path = %x(man -w asciidoctor).chop rescue ''
                 if manpage_path.empty?
                   $stderr.puts 'asciidoctor: FAILED: manual page not found; try `man asciidoctor`'
                   return 1
@@ -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
@@ -248,7 +249,7 @@ module Asciidoctor
 
         self[:input_files] = infiles
 
-        self.delete :attributes if self[:attributes].empty?
+        delete :attributes if self[:attributes].empty?
 
         if self[:template_dirs]
           begin
@@ -257,7 +258,7 @@ module Asciidoctor
             raise $! if self[:trace]
             $stderr.puts 'asciidoctor: FAILED: \'tilt\' could not be loaded'
             $stderr.puts '  You must have the tilt gem installed (gem install tilt) to use custom backend templates'
-            $stderr.puts '  Use --trace for backtrace'
+            $stderr.puts '  Use --trace to show backtrace'
             return 1
           rescue ::SystemExit
             # not permitted here
@@ -277,7 +278,7 @@ module Asciidoctor
             rescue ::LoadError
               raise $! if self[:trace]
               $stderr.puts %(asciidoctor: FAILED: '#{path}' could not be loaded)
-              $stderr.puts '  Use --trace for backtrace'
+              $stderr.puts '  Use --trace to show backtrace'
               return 1
             rescue ::SystemExit
               # not permitted here
@@ -289,11 +290,11 @@ module Asciidoctor
       rescue ::OptionParser::MissingArgument
         $stderr.puts %(asciidoctor: option #{$!.message})
         $stdout.puts opts_parser
-        return 1
+        1
       rescue ::OptionParser::InvalidOption, ::OptionParser::InvalidArgument
         $stderr.puts %(asciidoctor: #{$!.message})
         $stdout.puts opts_parser
-        return 1
+        1
       ensure
         $VERBOSE = old_verbose
       end