asciidoctor 2.0.6 → 2.0.11

data/lib/asciidoctor/abstract_block.rb

@@ -38,12 +38,13 @@ class AbstractBlock < AbstractNode
     @blocks = []
     @subs = []
     @id = @title = @caption = @numeral = @style = @default_subs = @source_location = nil
-    case context
-    when :document, :section
+    if context == :document || context == :section
       @level = @next_section_index = 0
       @next_section_ordinal = 1
+    elsif AbstractBlock === parent
+      @level = parent.level
     else
-      @level = AbstractBlock === parent ? parent.level : nil
+      @level = nil
     end
   end
 
@@ -140,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).
   #
@@ -222,6 +228,8 @@ class AbstractBlock < AbstractNode
         text = sub_specialchars text
         (ReplaceableTextRx.match? text) ? (sub_replacements text) : text
       end
+    else
+      ''
     end
   end
 
@@ -335,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 '. '
@@ -369,15 +377,15 @@ class AbstractBlock < AbstractNode
   # The parts of a complete caption are: <prefix> <number>. <title>
   # This partial caption represents the part the precedes the title.
   #
-  # value           - The explicit String caption to assign to this block (default: nil).
-  # caption_context - The Symbol context to use when resolving caption-related attributes.
-  #                   If not provided, the name of the context for this block is used.
+  # value           - The String caption to assign to this block or nil to use document attribute.
+  # caption_context - The Symbol context to use when resolving caption-related attributes. If not provided, the name of
+  #                   the context for this block is used. Only certain contexts allow the caption to be looked up.
   #                   (default: @context)
   #
   # Returns nothing.
-  def assign_caption value = nil, caption_context = @context
+  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
@@ -161,10 +161,10 @@ class AbstractNode
     nil
   end
 
-  # Public: Retrieve the Set of option names that are set on this node
+  # Public: Retrieve the Set of option names that are enabled on this node
   #
   # Returns a [Set] of option names
-  def options
+  def enabled_options
     ::Set.new.tap {|accum| @attributes.each_key {|k| accum << (k.slice 0, k.length - 7) if k.to_s.end_with? '-option' } }
   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 ndoe.
+  #
+  # 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.
@@ -310,14 +319,10 @@ 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) && (target_image = Helpers.encode_uri target_image)) ||
+      if ((Helpers.uriish? target_image) && (target_image = Helpers.encode_spaces_in_uri 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
+        (doc.attr? 'allow-uri-read') ? (generate_data_uri_from_uri target_image, (doc.attr? 'cache-uri')) : target_image
       else
         generate_data_uri target_image, asset_dir_key
       end
@@ -474,7 +479,7 @@ 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)
-      Helpers.encode_uri target
+      Helpers.encode_spaces_in_uri target
     else
       @document.path_resolver.web_path target, start
     end
@@ -518,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)
@@ -529,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 = {
-    '"' => /.*?[^\\](?=")/,
+    QUOT => /.*?[^\\](?=")/,
     APOS => /.*?[^\\](?=')/,
     ',' => /.*?(?=[ \t]*(,|$))/
   }
 
   # Public: Regular expressions for unescaping quoted characters
   EscapedQuotes = {
-    '"' => '\\"',
+    QUOT => '\\"',
     APOS => '\\\''
   }
 
@@ -45,7 +46,9 @@ class AttributeList
   BlankRx = /[ \t]+/
 
   # Public: Regular expressions for skipping delimiters
-  SkipRxs = { ',' => /[ \t]*(,|$)/ }
+  SkipRxs = {
+    ',' => /[ \t]*(,|$)/
+  }
 
   def initialize source, block = nil, delimiter = ','
     @scanner = ::StringScanner.new source
@@ -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
+      name = @block.apply_subs name if single_quoted && @block
       if (positional_attr_name = positional_attrs[index])
-        @attributes[positional_attr_name] = resolved_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

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

@@ -76,17 +76,17 @@ 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 key[=value]', 'a document attribute to set in the form of key, key! or key=value pair',
-                  'unless @ is appended to the value, this attributes takes precedence over attributes',
-                  'defined in the source document') do |attr|
+          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|
             next if (attr = attr.rstrip).empty? || attr == '='
             attr = attr.encode UTF_8 unless attr.encoding == UTF_8
-            key, _, val = attr.partition '='
-            self[:attributes][key] = val
+            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|
@@ -205,7 +205,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

data/lib/asciidoctor/convert.rb

@@ -0,0 +1,198 @@
+module Asciidoctor
+  class << self
+    # Public: Parse the AsciiDoc source input into an Asciidoctor::Document and
+    # convert it to the specified backend format.
+    #
+    # Accepts input as an IO (or StringIO), String or String Array object. If the
+    # input is a File, the object is expected to be opened for reading and is not
+    # closed afterwards by this method. Information about the file (filename,
+    # directory name, etc) gets assigned to attributes on the Document object.
+    #
+    # If the :to_file option is true, and the input is a File, the output is
+    # written to a file adjacent to the input file, having an extension that
+    # corresponds to the backend format. Otherwise, if the :to_file option is
+    # specified, the file is written to that file. If :to_file is not an absolute
+    # path, it is resolved relative to :to_dir, if given, otherwise the
+    # Document#base_dir. If the target directory does not exist, it will not be
+    # created unless the :mkdirs option is set to true. If the file cannot be
+    # written because the target directory does not exist, or because it falls
+    # outside of the Document#base_dir in safe mode, an IOError is raised.
+    #
+    # If the output is going to be written to a file, the header and footer are
+    # included unless specified otherwise (writing to a file implies creating a
+    # standalone document). Otherwise, the header and footer are not included by
+    # default and the converted result is returned.
+    #
+    # input   - the String AsciiDoc source filename
+    # options - a String, Array or Hash of options to control processing (default: {})
+    #           String and Array values are converted into a Hash.
+    #           See Asciidoctor::Document#initialize for details about options.
+    #
+    # Returns the Document object if the converted String is written to a
+    # file, otherwise the converted String
+    def convert input, options = {}
+      (options = options.merge).delete :parse
+      to_dir = options.delete :to_dir
+      mkdirs = options.delete :mkdirs
+
+      case (to_file = options.delete :to_file)
+      when true, nil
+        unless (write_to_target = to_dir)
+          sibling_path = ::File.absolute_path input.path if ::File === input
+        end
+        to_file = nil
+      when false
+        to_file = nil
+      when '/dev/null'
+        return load input, options
+      else
+        options[:to_file] = write_to_target = to_file unless (stream_output = to_file.respond_to? :write)
+      end
+
+      unless options.key? :standalone
+        if sibling_path || write_to_target
+          options[:standalone] = options.fetch :header_footer, true
+        elsif options.key? :header_footer
+          options[:standalone] = options[:header_footer]
+        end
+      end
+
+      # NOTE outfile may be controlled by document attributes, so resolve outfile after loading
+      if sibling_path
+        options[:to_dir] = outdir = ::File.dirname sibling_path
+      elsif write_to_target
+        if to_dir
+          if to_file
+            options[:to_dir] = ::File.dirname ::File.expand_path to_file, to_dir
+          else
+            options[:to_dir] = ::File.expand_path to_dir
+          end
+        elsif to_file
+          options[:to_dir] = ::File.dirname ::File.expand_path to_file
+        end
+      end
+
+      # NOTE :to_dir is always set when outputting to a file
+      # NOTE :to_file option only passed if assigned an explicit path
+      doc = load input, options
+
+      if sibling_path # write to file in same directory
+        outfile = ::File.join outdir, %(#{doc.attributes['docname']}#{doc.outfilesuffix})
+        raise ::IOError, %(input file and output file cannot be the same: #{outfile}) if outfile == sibling_path
+      elsif write_to_target # write to explicit file or directory
+        working_dir = (options.key? :base_dir) ? (::File.expand_path options[:base_dir]) : ::Dir.pwd
+        # QUESTION should the jail be the working_dir or doc.base_dir???
+        jail = doc.safe >= SafeMode::SAFE ? working_dir : nil
+        if to_dir
+          outdir = doc.normalize_system_path(to_dir, working_dir, jail, target_name: 'to_dir', recover: false)
+          if to_file
+            outfile = doc.normalize_system_path(to_file, outdir, nil, target_name: 'to_dir', recover: false)
+            # reestablish outdir as the final target directory (in the case to_file had directory segments)
+            outdir = ::File.dirname outfile
+          else
+            outfile = ::File.join outdir, %(#{doc.attributes['docname']}#{doc.outfilesuffix})
+          end
+        elsif to_file
+          outfile = doc.normalize_system_path(to_file, working_dir, jail, target_name: 'to_dir', recover: false)
+          # establish outdir as the final target directory (in the case to_file had directory segments)
+          outdir = ::File.dirname outfile
+        end
+
+        if ::File === input && outfile == (::File.absolute_path input.path)
+          raise ::IOError, %(input file and output file cannot be the same: #{outfile})
+        end
+
+        if mkdirs
+          Helpers.mkdir_p outdir
+        else
+          # NOTE we intentionally refer to the directory as it was passed to the API
+          raise ::IOError, %(target directory does not exist: #{to_dir} (hint: set :mkdirs option)) unless ::File.directory? outdir
+        end
+      else # write to stream
+        outfile = to_file
+        outdir = nil
+      end
+
+      if outfile && !stream_output
+        output = doc.convert 'outfile' => outfile, 'outdir' => outdir
+      else
+        output = doc.convert
+      end
+
+      if outfile
+        doc.write output, outfile
+
+        # NOTE document cannot control this behavior if safe >= SafeMode::SERVER
+        # NOTE skip if stylesdir is a URI
+        if !stream_output && doc.safe < SafeMode::SECURE && (doc.attr? 'linkcss') && (doc.attr? 'copycss') &&
+            (doc.basebackend? 'html') && !((stylesdir = (doc.attr 'stylesdir')) && (Helpers.uriish? stylesdir))
+          if (stylesheet = doc.attr 'stylesheet')
+            if DEFAULT_STYLESHEET_KEYS.include? stylesheet
+              copy_asciidoctor_stylesheet = true
+            elsif !(Helpers.uriish? stylesheet)
+              copy_user_stylesheet = true
+            end
+          end
+          copy_syntax_hl_stylesheet = (syntax_hl = doc.syntax_highlighter) && (syntax_hl.write_stylesheet? doc)
+          if copy_asciidoctor_stylesheet || copy_user_stylesheet || copy_syntax_hl_stylesheet
+            stylesoutdir = doc.normalize_system_path(stylesdir, outdir, doc.safe >= SafeMode::SAFE ? outdir : nil)
+            if mkdirs
+              Helpers.mkdir_p stylesoutdir
+            else
+              raise ::IOError, %(target stylesheet directory does not exist: #{stylesoutdir} (hint: set :mkdirs option)) unless ::File.directory? stylesoutdir
+            end
+
+            if copy_asciidoctor_stylesheet
+              Stylesheets.instance.write_primary_stylesheet stylesoutdir
+            # FIXME should Stylesheets also handle the user stylesheet?
+            elsif copy_user_stylesheet
+              if (stylesheet_src = doc.attr 'copycss') == '' || stylesheet_src == true
+                stylesheet_src = doc.normalize_system_path stylesheet
+              else
+                # NOTE in this case, copycss is a source location (but cannot be a URI)
+                stylesheet_src = doc.normalize_system_path stylesheet_src.to_s
+              end
+              stylesheet_dest = doc.normalize_system_path stylesheet, stylesoutdir, (doc.safe >= SafeMode::SAFE ? outdir : nil)
+              # NOTE don't warn if src can't be read and dest already exists (see #2323)
+              if stylesheet_src != stylesheet_dest && (stylesheet_data = doc.read_asset stylesheet_src,
+                  warn_on_failure: !(::File.file? stylesheet_dest), label: 'stylesheet')
+                if (stylesheet_outdir = ::File.dirname stylesheet_dest) != stylesoutdir && !(::File.directory? stylesheet_outdir)
+                  if mkdirs
+                    Helpers.mkdir_p stylesheet_outdir
+                  else
+                    raise ::IOError, %(target stylesheet directory does not exist: #{stylesheet_outdir} (hint: set :mkdirs option))
+                  end
+                end
+                ::File.write stylesheet_dest, stylesheet_data, mode: FILE_WRITE_MODE
+              end
+            end
+            syntax_hl.write_stylesheet doc, stylesoutdir if copy_syntax_hl_stylesheet
+          end
+        end
+        doc
+      else
+        output
+      end
+    end
+
+    # Public: Parse the contents of the AsciiDoc source file into an
+    # Asciidoctor::Document and convert it to the specified backend format.
+    #
+    # input   - the String AsciiDoc source filename
+    # options - a String, Array or Hash of options to control processing (default: {})
+    #           String and Array values are converted into a Hash.
+    #           See Asciidoctor::Document#initialize for details about options.
+    #
+    # Returns the Document object if the converted String is written to a
+    # file, otherwise the converted String
+    def convert_file filename, options = {}
+      ::File.open(filename, FILE_READ_MODE) {|file| convert file, options }
+    end
+
+    # Deprecated: Use {Asciidoctor.convert} instead.
+    alias render convert
+
+    # Deprecated: Use {Asciidoctor.convert_file} instead.
+    alias render_file convert_file
+  end
+end