asciidoctor 1.5.5 → 1.5.6

data/lib/asciidoctor/abstract_block.rb

@@ -13,14 +13,16 @@ class AbstractBlock < AbstractNode
   # Public: Set the Integer level of this Section or the Section level in which this Block resides
   attr_accessor :level
 
-  # Public: Set the String block title.
-  attr_writer :title
-
   # Public: Get/Set the String style (block type qualifier) for this block.
   attr_accessor :style
 
-  # Public: Get/Set the caption for this block
-  attr_accessor :caption
+  # Public: Set the caption for this block
+  attr_writer :caption
+
+  # Public: Get/Set the number of this block (if section, relative to parent, otherwise absolute)
+  # Only assigned to section if automatic section numbering is enabled
+  # Only assigned to formal block (block with title) if corresponding caption attribute is present
+  attr_accessor :number
 
   # Public: Gets/Sets the location in the AsciiDoc source where this block begins
   attr_accessor :source_location
@@ -28,21 +30,18 @@ class AbstractBlock < AbstractNode
   def initialize parent, context, opts = {}
     super
     @content_model = :compound
-    @subs = []
-    @default_subs = nil
     @blocks = []
-    @id = nil
-    @title = nil
-    @caption = nil
-    @style = nil
-    @level = if context == :document
-      0
+    @subs = []
+    @id = @title = @title_converted = @caption = @number = @style = @default_subs = @source_location = nil
+    if context == :document
+      @level = 0
     elsif parent && context != :section
-      parent.level
+      @level = parent.level
+    else
+      @level = nil
     end
     @next_section_index = 0
     @next_section_number = 1
-    @source_location = nil
   end
 
   def block?
@@ -72,12 +71,12 @@ class AbstractBlock < AbstractNode
   end
 
   # Alias render to convert to maintain backwards compatibility
-  alias :render :convert
+  alias render convert
 
   # Public: Get the converted result of the child blocks by converting the
   # children appropriate to content model that this block supports.
   def content
-    @blocks.map {|b| b.convert } * EOL
+    @blocks.map {|b| b.convert } * LF
   end
 
   # Public: Get the source file where this block started
@@ -101,10 +100,11 @@ class AbstractBlock < AbstractNode
     @subs.include? name
   end
 
-  # Public: A convenience method that indicates whether the title instance
-  # variable is blank (nil or empty)
+  # Public: A convenience method that checks whether the title of this block is defined.
+  #
+  # Returns a [Boolean] indicating whether this block has a title.
   def title?
-    !@title.nil_or_empty?
+    @title ? true : false
   end
 
   # Public: Get the String title of this Block with title substitions applied
@@ -119,16 +119,28 @@ class AbstractBlock < AbstractNode
   #   block.title
   #   => "Foo 3^ # :: Bar(1)"
   #
-  # Returns the String title of this Block
+  # Returns the converted String title for this Block, or nil if the source title is falsy
   def title
-    # prevent substitutions from being applied multiple times
-    if defined?(@subbed_title)
-      @subbed_title
-    elsif @title
-      @subbed_title = apply_title_subs(@title)
-    else
-      @title
-    end
+    # prevent substitutions from being applied to title multiple times
+    @title_converted ? @converted_title : (@converted_title = (@title_converted = true) && @title && (apply_title_subs @title))
+  end
+
+  # Public: Set the String block title.
+  #
+  # Returns the new String title assigned to this Block
+  def title= val
+    @title, @title_converted = val, nil
+  end
+
+  # Gets the caption for this block.
+  #
+  # This method routes the deprecated use of the caption method on an
+  # admonition block to the textlabel attribute.
+  #
+  # Returns the [String] caption for this block (or the value of the textlabel
+  # attribute if this is an admonition block).
+  def caption
+    @context == :admonition ? @attributes['textlabel'] : @caption
   end
 
   # Public: Convenience method that returns the interpreted title of the Block
@@ -139,12 +151,70 @@ class AbstractBlock < AbstractNode
   # two values. If the Block does not have a caption, the interpreted title is
   # returned.
   #
-  # Returns the String title prefixed with the caption, or just the title if no
-  # caption is set
+  # Returns the converted String title prefixed with the caption, or just the
+  # converted String title if no caption is set
   def captioned_title
     %(#{@caption}#{title})
   end
 
+  # Public: Returns the converted alt text for this block image.
+  #
+  # Returns the [String] value of the alt attribute with XML special character
+  # and replacement substitutions applied.
+  def alt
+    if (text = @attributes['alt'])
+      if text == @attributes['default-alt']
+        sub_specialchars text
+      else
+        text = sub_specialchars text
+        (ReplaceableTextRx.match? text) ? (sub_replacements text) : text
+      end
+    end
+  end
+
+  # Public: Generate cross reference text (xreftext) that can be used to refer
+  # to this block.
+  #
+  # Use the explicit reftext for this block, if specified, retrieved from the
+  # {#reftext} method. Otherwise, if this is a section or captioned block (a
+  # block with both a title and caption), generate the xreftext according to
+  # the value of the xrefstyle argument (e.g., full, short). This logic may
+  # leverage the {Substitutors#sub_quotes} method to apply formatting to the
+  # text. If this is not a captioned block, return the title, if present, or
+  # nil otherwise.
+  #
+  # xrefstyle - An optional String that specifies the style to use to format
+  #             the xreftext ('full', 'short', or 'basic') (default: nil).
+  #
+  # Returns the generated [String] xreftext used to refer to this block or
+  # nothing if there isn't sufficient information to generate one.
+  def xreftext xrefstyle = nil
+    if (val = reftext) && !val.empty?
+      val
+    # NOTE xrefstyle only applies to blocks with a title and a caption or number
+    elsif xrefstyle && @title && @caption
+      case xrefstyle
+      when 'full'
+        quoted_title = sprintf sub_quotes(@document.compat_mode ? %q(``%s'') : '"`%s`"'), title
+        if @number && (prefix = @document.attributes[@context == :image ? 'figure-caption' : %(#{@context}-caption)])
+          %(#{prefix} #{@number}, #{quoted_title})
+        else
+          %(#{@caption.chomp '. '}, #{quoted_title})
+        end
+      when 'short'
+        if @number && (prefix = @document.attributes[@context == :image ? 'figure-caption' : %(#{@context}-caption)])
+          %(#{prefix} #{@number})
+        else
+          @caption.chomp '. '
+        end
+      else # 'basic'
+        title
+      end
+    else
+      title
+    end
+  end
+
   # Public: Determine whether this Block contains block content
   #
   # Returns A Boolean indicating whether this Block has block content
@@ -176,7 +246,7 @@ class AbstractBlock < AbstractNode
   end
 
   # NOTE append alias required for adapting to a Java API
-  alias :append :<<
+  alias append <<
 
   # Public: Get the Array of child Section objects
   #
@@ -307,7 +377,13 @@ class AbstractBlock < AbstractNode
     end
     result
   end
-  alias :query :find_by
+  alias query find_by
+
+  # Move to the next adjacent block in document order. If the current block is the last
+  # item in a list, this method will return the following sibling of the list block.
+  def next_adjacent_block
+    (sib = (p = parent).blocks[(p.blocks.find_index self) + 1]) ? sib : p.next_adjacent_block unless @context == :document
+  end
 
   # Public: Remove a substitution from this block
   #
@@ -319,39 +395,53 @@ class AbstractBlock < AbstractNode
     nil
   end
 
-  # Public: Generate a caption and assign it to this block if one
-  # is not already assigned.
+  # Public: Generate and assign caption to block if not already assigned.
   #
-  # If the block has a title and a caption prefix is available
-  # for this block, then build a caption from this information,
-  # assign it a number and store it to the caption attribute on
-  # the block.
+  # If the block has a title and a caption prefix is available for this block,
+  # then build a caption from this information, assign it a number and store it
+  # to the caption attribute on the block.
   #
-  # If an explicit caption has been specified on this block, then
-  # do nothing.
+  # If a caption has already been assigned to this block, do nothing.
   #
-  # key         - The prefix of the caption and counter attribute names.
-  #               If not provided, the name of the context for this block
-  #               is used. (default: nil).
+  # The parts of a complete caption are: <prefix> <number>. <title>
+  # This partial caption represents the part the precedes the title.
   #
-  # Returns nothing
-  def assign_caption(caption = nil, key = nil)
-    return unless title? || !@caption
-
-    if caption
-      @caption = caption
-    else
-      if (value = @document.attributes['caption'])
-        @caption = value
-      elsif title?
-        key ||= @context.to_s
-        caption_key = "#{key}-caption"
-        if (caption_title = @document.attributes[caption_key])
-          caption_num = @document.counter_increment("#{key}-number", self)
-          @caption = "#{caption_title} #{caption_num}. "
-        end
+  # value - The explicit String caption to assign to this block (default: nil).
+  # key   - The String prefix for the caption and counter attribute names.
+  #         If not provided, the name of the context for this block is used.
+  #         (default: nil)
+  #
+  # Returns nothing.
+  def assign_caption value = nil, key = nil
+    unless @caption || !@title || (@caption = value || @document.attributes['caption'])
+      if (prefix = @document.attributes[%(#{key ||= @context}-caption)])
+        @caption = %(#{prefix} #{@number = @document.increment_and_store_counter "#{key}-number", self}. )
+        nil
       end
     end
+  end
+
+  # Internal: Assign the next index (0-based) and number (1-based) to the section
+  #
+  # Assign to the specified section the next index and, if the section is
+  # numbered, number within this block (its parent).
+  #
+  # Returns nothing
+  def enumerate_section section
+    @next_section_index = (section.index = @next_section_index) + 1
+    if (sectname = section.sectname) == 'appendix'
+      section.number = @document.counter 'appendix-number', 'A'
+      if (caption = @document.attributes['appendix-caption'])
+        section.caption = %(#{caption} #{section.number}: )
+      else
+        section.caption = %(#{section.number}. )
+      end
+    # NOTE currently chapters in a book doctype are sequential even for multi-part books (see #979)
+    elsif sectname == 'chapter'
+      section.number = @document.counter 'chapter-number', 1
+    else
+      @next_section_number = (section.number = @next_section_number) + 1
+    end if section.numbered
     nil
   end
 
@@ -366,35 +456,6 @@ class AbstractBlock < AbstractNode
     ORDERED_LIST_KEYWORDS[list_type || @style]
   end
 
-  # Internal: Assign the next index (0-based) to this section
-  #
-  # Assign the next index of this section within the parent
-  # Block (in document order)
-  #
-  # Returns nothing
-  def assign_index(section)
-    section.index = @next_section_index
-    @next_section_index += 1
-
-    if section.sectname == 'appendix'
-      appendix_number = @document.counter 'appendix-number', 'A'
-      section.number = appendix_number if section.numbered
-      if (caption = @document.attr 'appendix-caption', '').empty?
-        section.caption = %(#{appendix_number}. )
-      else
-        section.caption = %(#{caption} #{appendix_number}: )
-      end
-    elsif section.numbered
-      # chapters in a book doctype should be sequential even when divided into parts
-      if (section.level == 1 || (section.level == 0 && section.special)) && @document.doctype == 'book'
-        section.number = @document.counter('chapter-number', 1)
-      else
-        section.number = @next_section_number
-        @next_section_number += 1
-      end
-    end
-  end
-
   # Internal: Reassign the section indexes
   #
   # Walk the descendents of the current Document or Section
@@ -403,17 +464,17 @@ class AbstractBlock < AbstractNode
   #
   # IMPORTANT You must invoke this method on a node after removing
   # child sections or else the internal counters will be off.
-  # 
+  #
   # Returns nothing
   def reindex_sections
     @next_section_index = 0
-    @next_section_number = 0
-    @blocks.each {|block|
+    @next_section_number = 1
+    @blocks.each do |block|
       if block.context == :section
-        assign_index(block)
+        enumerate_section block
         block.reindex_sections
       end
-    }
+    end
   end
 end
 end

data/lib/asciidoctor/abstract_node.rb

@@ -26,20 +26,17 @@ class AbstractNode
   attr_reader :attributes
 
   def initialize parent, context, opts = {}
-    # document is a special case, should refer to itself
     if context == :document
-      @document = parent
+      # document is a special case, should refer to itself
+      @document, @parent = self, nil
     else
       if parent
-        @parent = parent
-        @document = parent.document
+        @document, @parent = parent.document, parent
       else
-        @parent = nil
-        @document = nil
+        @document = @parent = nil
       end
     end
-    @context = context
-    @node_name = context.to_s
+    @node_name = (@context = context).to_s
     # QUESTION are we correct in duplicating the attributes (seems to be just as fast)
     @attributes = (opts.key? :attributes) ? opts[:attributes].dup : {}
     @passthroughs = {}
@@ -51,8 +48,7 @@ class AbstractNode
   #
   # Returns nothing
   def parent=(parent)
-    @parent = parent
-    @document = parent.document
+    @parent, @document = parent, parent.document
     nil
   end
 
@@ -82,21 +78,17 @@ class AbstractNode
   # Document node and return the value of the attribute if found. Otherwise,
   # return the default value, which defaults to nil.
   #
-  # name          - the String or Symbol name of the attribute to lookup
-  # default_value - the Object value to return if the attribute is not found (default: nil)
-  # inherit       - a Boolean indicating whether to check for the attribute on the
-  #                 AsciiDoctor::Document if not found on this node (default: false)
+  # name        - the String or Symbol name of the attribute to lookup
+  # default_val - the Object value to return if the attribute is not found (default: nil)
+  # inherit     - a Boolean indicating whether to check for the attribute on the
+  #               AsciiDoctor::Document if not found on this node (default: false)
   #
   # return the value of the attribute or the default value if the attribute
   # is not found in the attributes of this node or the document node
-  def attr(name, default_value = nil, inherit = true)
-    name = name.to_s if ::Symbol === name
-    inherit = false if self == @document
-    if inherit
-      @attributes[name] || @document.attributes[name] || default_value
-    else
-      @attributes[name] || default_value
-    end
+  def attr name, default_val = nil, inherit = true
+    name = name.to_s
+    # NOTE if @parent is set, it means @document is also set
+    @attributes[name] || (inherit && @parent ? @document.attributes[name] || default_val : default_val)
   end
 
   # Public: Check if the attribute is defined, optionally performing a
@@ -108,35 +100,33 @@ class AbstractNode
   # comparison value is specified (not nil), return whether the two values match.
   # Otherwise, return whether the attribute was found.
   #
-  # name    - the String or Symbol name of the attribute to lookup
-  # expect  - the expected Object value of the attribute (default: nil)
-  # inherit - a Boolean indicating whether to check for the attribute on the
-  #           AsciiDoctor::Document if not found on this node (default: false)
+  # name       - the String or Symbol name of the attribute to lookup
+  # expect_val - the expected Object value of the attribute (default: nil)
+  # inherit    - a Boolean indicating whether to check for the attribute on the
+  #              AsciiDoctor::Document if not found on this node (default: false)
   #
   # return a Boolean indicating whether the attribute exists and, if a
   # comparison value is specified, whether the value of the attribute matches
   # the comparison value
-  def attr?(name, expect = nil, inherit = true)
-    name = name.to_s if ::Symbol === name
-    inherit = false if self == @document
-    if expect.nil?
-      @attributes.has_key?(name) || (inherit && @document.attributes.has_key?(name))
-    elsif inherit
-      expect == (@attributes[name] || @document.attributes[name])
+  def attr? name, expect_val = nil, inherit = true
+    name = name.to_s
+    # NOTE if @parent is set, it means @document is also set
+    if expect_val.nil?
+      (@attributes.key? name) || (inherit && @parent && (@document.attributes.key? name))
     else
-      expect == @attributes[name]
+      expect_val == (@attributes[name] || (inherit && @parent ? @document.attributes[name] : nil))
     end
   end
 
   # Public: Assign the value to the attribute name for the current node.
   #
   # name      - The String attribute name to assign
-  # value     - The Object value to assign to the attribute
+  # value     - The Object value to assign to the attribute (default: '')
   # overwrite - A Boolean indicating whether to assign the attribute
   #             if currently present in the attributes Hash (default: true)
   #
   # Returns a [Boolean] indicating whether the assignment was performed
-  def set_attr name, value, overwrite = true
+  def set_attr name, value = '', overwrite = true
     if overwrite == false && (@attributes.key? name)
       false
     else
@@ -145,14 +135,23 @@ class AbstractNode
     end
   end
 
+  # Public: Remove the attribute from the current node.
+  #
+  # name      - The String attribute name to remove
+  #
+  # Returns the previous [String] value, or nil if the attribute was not present.
+  def remove_attr name
+    @attributes.delete name
+  end
+
   # TODO document me
   def set_option(name)
-    if @attributes.has_key? 'options'
-      @attributes['options'] = "#{@attributes['options']},#{name}"
+    if @attributes.key? 'options'
+      @attributes['options'] = %(#{@attributes['options']},#{name})
     else
       @attributes['options'] = name
     end
-    @attributes["#{name}-option"] = ''
+    @attributes[%(#{name}-option)] = ''
   end
 
   # Public: A convenience method to check if the specified option attribute is
@@ -165,7 +164,7 @@ class AbstractNode
   #
   # return a Boolean indicating whether the option has been specified
   def option?(name)
-    @attributes.has_key? %(#{name}-option)
+    @attributes.key? %(#{name}-option)
   end
 
   # Public: Update the attributes of this node with the new values in
@@ -189,11 +188,11 @@ class AbstractNode
   end
 
   # Public: A convenience method that checks if the role attribute is specified
-  def role?(expect = nil)
-    if expect
-      expect == (@attributes['role'] || @document.attributes['role'])
+  def role? expect_val = nil
+    if expect_val
+      expect_val == (@attributes['role'] || @document.attributes['role'])
     else
-      @attributes.has_key?('role') || @document.attributes.has_key?('role')
+      @attributes.key?('role') || @document.attributes.key?('role')
     end
   end
 
@@ -205,45 +204,59 @@ class AbstractNode
   # Public: A convenience method that checks if the specified role is present
   # in the list of roles on this node
   def has_role?(name)
-    if (val = (@attributes['role'] || @document.attributes['role']))
-      val.split(' ').include?(name)
-    else
-      false
-    end
+    # NOTE center + include? is faster than split + include?
+    (val = @attributes['role'] || @document.attributes['role']).nil_or_empty? ? false : %( #{val} ).include?(%( #{name} ))
   end
 
   # Public: A convenience method that returns the role names as an Array
+  #
+  # Returns the role names as an Array or an empty Array if the role attribute is absent.
   def roles
-    if (val = (@attributes['role'] || @document.attributes['role']))
-      val.split(' ')
-    else
-      []
-    end
+    (val = @attributes['role'] || @document.attributes['role']).nil_or_empty? ? [] : val.split
   end
 
   # Public: A convenience method that adds the given role directly to this node
+  #
+  # Returns a Boolean indicating whether the role was added.
   def add_role(name)
-    unless (roles = (@attributes['role'] || '').split(' ')).include? name
-      @attributes['role'] = roles.push(name) * ' '
+    if (val = @attributes['role']).nil_or_empty?
+      @attributes['role'] = name
+      true
+    # NOTE center + include? is faster than split + include?
+    elsif %( #{val} ).include?(%( #{name} ))
+      false
+    else
+      @attributes['role'] = %(#{val} #{name})
+      true
     end
   end
 
   # Public: A convenience method that removes the given role directly from this node
+  #
+  # Returns a Boolean indicating whether the role was removed.
   def remove_role(name)
-    if (roles = (@attributes['role'] || '').split(' ')).include? name
-      roles.delete name
-      @attributes['role'] = roles * ' '
+    if (val = @attributes['role']).nil_or_empty?
+      false
+    elsif (val = val.split).delete name
+      if val.empty?
+        @attributes.delete('role')
+      else
+        @attributes['role'] = val * ' '
+      end
+      true
+    else
+      false
     end
   end
 
-  # Public: A convenience method that checks if the reftext attribute is specified
+  # Public: A convenience method that checks if the reftext attribute is defined.
   def reftext?
-    @attributes.has_key?('reftext') || @document.attributes.has_key?('reftext')
+    @attributes.key? 'reftext'
   end
 
-  # Public: A convenience method that returns the value of the reftext attribute
+  # Public: A convenience method that returns the value of the reftext attribute with substitutions applied.
   def reftext
-    @attributes['reftext'] || @document.attributes['reftext']
+    (val = @attributes['reftext']) ? (apply_reftext_subs val) : nil
   end
 
   # Public: Construct a reference or data URI to an icon image for the
@@ -315,12 +328,12 @@ class AbstractNode
   #
   # Returns A String reference or data URI for the target image
   def image_uri(target_image, asset_dir_key = 'imagesdir')
-    if (doc = @document).safe < SafeMode::SECURE && doc.attr?('data-uri')
-      if (Helpers.uriish? target_image) ||
-          (asset_dir_key && (images_base = doc.attr(asset_dir_key)) && (Helpers.uriish? images_base) &&
-          (target_image = normalize_web_path(target_image, images_base, false)))
-        if doc.attr?('allow-uri-read')
-          generate_data_uri_from_uri target_image, doc.attr?('cache-uri')
+    if (doc = @document).safe < SafeMode::SECURE && (doc.attr? 'data-uri')
+      if ((Helpers.uriish? target_image) && (target_image = uri_encode_spaces target_image)) ||
+          (asset_dir_key && (images_base = doc.attr asset_dir_key) && (Helpers.uriish? images_base) &&
+          (target_image = normalize_web_path target_image, images_base, false))
+        if doc.attr? 'allow-uri-read'
+          generate_data_uri_from_uri target_image, (doc.attr? 'cache-uri')
         else
           target_image
         end
@@ -328,7 +341,7 @@ class AbstractNode
         generate_data_uri target_image, asset_dir_key
       end
     else
-      normalize_web_path target_image, (asset_dir_key ? doc.attr(asset_dir_key) : nil)
+      normalize_web_path target_image, (asset_dir_key ? (doc.attr asset_dir_key) : nil)
     end
   end
 
@@ -356,20 +369,13 @@ class AbstractNode
 
     unless ::File.readable? image_path
       warn %(asciidoctor: WARNING: image to embed not found or not readable: #{image_path})
-      # must enclose string following return in " for Opal
-      return "data:#{mimetype}:base64,"
+      return %(data:#{mimetype};base64,)
       # uncomment to return 1 pixel white dot instead
       #return 'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=='
     end
 
-    bindata = nil
-    if ::IO.respond_to? :binread
-      bindata = ::IO.binread(image_path)
-    else
-      bindata = ::File.open(image_path, 'rb') {|file| file.read }
-    end
     # NOTE base64 is autoloaded by reference to ::Base64
-    %(data:#{mimetype};base64,#{::Base64.encode64(bindata).delete EOL})
+    %(data:#{mimetype};base64,#{::Base64.encode64(::IO.binread image_path).delete LF})
   end
 
   # Public: Read the image data from the specified URI and generate a data URI
@@ -396,12 +402,12 @@ class AbstractNode
 
     begin
       mimetype = nil
-      bindata = open(image_uri, 'rb') {|file|
-        mimetype = file.content_type
-        file.read
+      bindata = open(image_uri, 'rb') {|fd|
+        mimetype = fd.content_type
+        fd.read
       }
       # NOTE base64 is autoloaded by reference to ::Base64
-      %(data:#{mimetype};base64,#{::Base64.encode64(bindata).delete EOL})
+      %(data:#{mimetype};base64,#{::Base64.encode64(bindata).delete LF})
     rescue
       warn %(asciidoctor: WARNING: could not retrieve image data from URI: #{image_uri})
       image_uri
@@ -436,7 +442,7 @@ class AbstractNode
         Helpers.require_library 'open-uri/cached', 'open-uri-cached' if doc.attr? 'cache-uri'
         begin
           data = ::OpenURI.open_uri(target) {|fd| fd.read }
-          data = (Helpers.normalize_lines_from_string data) * EOL if opts[:normalize]
+          data = (Helpers.normalize_lines_from_string data) * LF if opts[:normalize]
         rescue
           warn %(asciidoctor: WARNING: could not retrieve contents of #{opts[:label] || 'asset'} at URI: #{target}) if opts.fetch :warn_on_failure, true
           data = nil
@@ -447,7 +453,7 @@ class AbstractNode
       end
     else
       target = normalize_system_path target, opts[:start], nil, :target_name => (opts[:label] || 'asset')
-      data = read_asset target, :normalize => opts[:normalize], :warn_on_failure => (opts.fetch :warn_on_failure, true)
+      data = read_asset target, :normalize => opts[:normalize], :warn_on_failure => (opts.fetch :warn_on_failure, true), :label => opts[:label]
     end
     data
   end
@@ -465,25 +471,24 @@ class AbstractNode
   #
   # Returns the [String] content of the file at the specified path, or nil
   # if the file does not exist.
-  def read_asset(path, opts = {})
+  def read_asset path, opts = {}
     # remap opts for backwards compatibility
     opts = { :warn_on_failure => (opts != false) } unless ::Hash === opts
     if ::File.readable? path
       if opts[:normalize]
-        Helpers.normalize_lines_from_string(::IO.read(path)) * EOL
+        Helpers.normalize_lines_from_string(::IO.read path) * LF
       else
         # QUESTION should we chomp or rstrip content?
-        ::IO.read(path)
+        ::IO.read path
       end
-    else
-      warn %(asciidoctor: WARNING: file does not exist or cannot be read: #{path}) if opts[:warn_on_failure]
-      nil
+    elsif opts[:warn_on_failure]
+      warn %(asciidoctor: WARNING: #{(attr 'docfile') || '<stdin>'}: #{opts[:label] || 'file'} does not exist or cannot be read: #{path})
     end
   end
 
-  # Public: Normalize the web page using the PathResolver.
+  # Public: Normalize the web path using the PathResolver.
   #
-  # See {PathResolver#web_path} for details.
+  # See {PathResolver#web_path} for details about path resolution and encoding.
   #
   # target              - the String target path
   # start               - the String start (i.e, parent) path (optional, default: nil)
@@ -492,12 +497,21 @@ class AbstractNode
   # Returns the resolved [String] path
   def normalize_web_path(target, start = nil, preserve_uri_target = true)
     if preserve_uri_target && (Helpers.uriish? target)
-      target
+      uri_encode_spaces target
     else
       (@path_resolver ||= PathResolver.new).web_path target, start
     end
   end
 
+  # Internal: URI encode spaces in a String
+  #
+  # str - the String to encode
+  #
+  # Returns the String with all spaces replaced with %20.
+  def uri_encode_spaces str
+    (str.include? ' ') ? (str.gsub ' ', '%20') : str
+  end
+
   # Public: Resolve and normalize a secure path from the target and start paths
   # using the PathResolver.
   #