asciidoctor 1.5.8 → 2.0.17

data/lib/asciidoctor/cli/options.rb

@@ -1,33 +1,30 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 module Asciidoctor
   module Cli
-    FS = '/'
-    RS = '\\'
+    FS = ?/
+    RS = ?\\
 
     # Public: List of options that can be specified on the command line
     class Options < ::Hash
 
       def initialize(options = {})
         self[:attributes] = options[:attributes] || {}
-        self[:input_files] = options[:input_files] || nil
-        self[:output_file] = options[:output_file] || nil
+        self[:input_files] = options[:input_files]
+        self[:output_file] = options[:output_file]
         self[:safe] = options[:safe] || SafeMode::UNSAFE
-        self[:header_footer] = options[:header_footer] || true
-        self[:template_dirs] = options[:template_dirs] || nil
-        self[:template_engine] = options[:template_engine] || nil
-        if options[:doctype]
-          self[:attributes]['doctype'] = options[:doctype]
-        end
-        if options[:backend]
-          self[:attributes]['backend'] = options[:backend]
-        end
-        self[:eruby] = options[:eruby] || nil
-        self[:verbose] = options[:verbose] || 1
-        self[:load_paths] = options[:load_paths] || nil
-        self[:requires] = options[:requires] || nil
+        self[:standalone] = options.fetch :standalone, true
+        self[:template_dirs] = options[:template_dirs]
+        self[:template_engine] = options[:template_engine]
+        self[:attributes]['doctype'] = options[:doctype] if options[:doctype]
+        self[:attributes]['backend'] = options[:backend] if options[:backend]
+        self[:eruby] = options[:eruby]
+        self[:verbose] = options.fetch :verbose, 1
+        self[:warnings] = options.fetch :warnings, false
+        self[:load_paths] = options[:load_paths]
+        self[:requires] = options[:requires]
         self[:base_dir] = options[:base_dir]
-        self[:source_dir] = options[:source_dir] || nil
-        self[:destination_dir] = options[:destination_dir] || nil
+        self[:source_dir] = options[:source_dir]
+        self[:destination_dir] = options[:destination_dir]
         self[:failure_level] = ::Logger::Severity::FATAL
         self[:trace] = false
         self[:timings] = false
@@ -39,55 +36,61 @@ module Asciidoctor
 
       def parse!(args)
         opts_parser = ::OptionParser.new do |opts|
-          opts.banner = <<-EOS
-Usage: asciidoctor [OPTION]... FILE...
-Translate the AsciiDoc source FILE or FILE(s) into the backend output format (e.g., HTML 5, DocBook 4.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
+          # NOTE don't use squiggly heredoc to maintain compatibility with Ruby < 2.3
+          opts.banner = <<-'EOS'.gsub '          ', ''
+          Usage: asciidoctor [OPTION]... FILE...
+          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, docbook45, 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
           end
           opts.on('-o', '--out-file FILE', 'output file (default: based on path of input file); use - to output to STDOUT') do |output_file|
             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 output of header and footer (default: false)') do
-            self[:header_footer] = false
+          opts.on('-s', '--no-header-footer', 'suppress enclosing document structure and output an embedded document (default: false)') do
+            self[:standalone] = false
           end
           opts.on('-n', '--section-numbers', 'auto-number section titles in the HTML backend; disabled by default') do
             self[:attributes]['sectnums'] = ''
           end
-          opts.on('-e', '--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|
-            key, val = attr.split '=', 2
-            val = val ? (FORCE_ENCODING ? (val.force_encoding ::Encoding::UTF_8) : val) : ''
-            self[:attributes][key] = val
+          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
+            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]
@@ -116,44 +119,49 @@ Example: asciidoctor -b html5 source.asciidoc
               'may be specified more than once') do |path|
             (self[:requires] ||= []).concat(path.split ',')
           end
-          opts.on('--failure-level LEVEL', %w(warning WARNING error ERROR), 'set minimum logging level that triggers a non-zero exit code: [WARN, ERROR] (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
           end
-          opts.on('-q', '--quiet', 'suppress 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 on 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('-t', '--timings', 'enable timings mode (default: false)') do |timing|
+          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
             self[:timings] = true
           end
-
-          opts.on_tail('-h', '--help [TOPIC]', 'print the help message',
-              'show the command usage if TOPIC is not specified (or not recognized)',
+          opts.on_tail('-h', '--help [TOPIC]', 'print a help message',
+              'show this usage if TOPIC is not specified or recognized',
+              'show an overview of the AsciiDoc syntax if TOPIC is syntax',
               'dump the Asciidoctor man page (in troff/groff format) if TOPIC is manpage') do |topic|
-            if topic == 'manpage'
-              if (manpage_path = ENV['ASCIIDOCTOR_MANPAGE_PATH'])
+            case topic
+            # use `asciidoctor -h manpage | man -l -` to view with man pager
+            when 'manpage'
+              if (manpage_path = ::ENV['ASCIIDOCTOR_MANPAGE_PATH'])
                 if ::File.exist? manpage_path
                   if manpage_path.end_with? '.gz'
                     require 'zlib' unless defined? ::Zlib::GzipReader
                     $stdout.puts ::Zlib::GzipReader.open(manpage_path) {|gz| gz.read }
                   else
-                    $stdout.puts ::IO.read manpage_path
+                    $stdout.puts ::File.read manpage_path
                   end
                 else
                   $stderr.puts %(asciidoctor: FAILED: manual page not found: #{manpage_path})
                   return 1
                 end
-              elsif ::File.exist?(manpage_path = (::File.join ::Asciidoctor::ROOT_PATH, 'man', 'asciidoctor.1'))
-                $stdout.puts ::IO.read manpage_path
+              # Ruby 2.3 requires the extra brackets around the ::File.join method call
+              elsif ::File.exist? (manpage_path = (::File.join ROOT_DIR, 'man', 'asciidoctor.1'))
+                $stdout.puts ::File.read manpage_path
               else
-                require 'open3' unless defined? ::Open3.popen3
-                manpage_path = ::Open3.popen3('man -w asciidoctor') {|_, out| out.read }.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
@@ -161,26 +169,32 @@ Example: asciidoctor -b html5 source.asciidoc
                   require 'zlib' unless defined? ::Zlib::GzipReader
                   $stdout.puts ::Zlib::GzipReader.open(manpage_path) {|gz| gz.read }
                 else
-                  $stdout.puts ::IO.read manpage_path
+                  $stdout.puts ::File.read manpage_path
                 end
               end
+            when 'syntax'
+              # Ruby 2.3 requires the extra brackets around the ::File.join method call
+              if ::File.exist? (syntax_path = (::File.join ROOT_DIR, 'data', 'reference', 'syntax.adoc'))
+                $stdout.puts ::File.read syntax_path
+              else
+                $stderr.puts 'asciidoctor: FAILED: syntax page not found; visit https://asciidoctor.org/docs'
+                return 1
+              end
             else
               $stdout.puts opts
             end
             return 0
           end
-
           opts.on_tail('-V', '--version', 'display the version and runtime environment (or -v if no other flags or arguments)') do
             return print_version $stdout
           end
-
         end
 
-        infiles = []
+        old_verbose, $VERBOSE = $VERBOSE, (args.include? '-w')
         opts_parser.parse! args
 
         if args.empty?
-          if self[:verbose] == 2
+          if self[:verbose] == 2 # -v flag was specified
             return print_version $stdout
           else
             $stderr.puts opts_parser
@@ -188,29 +202,28 @@ Example: asciidoctor -b html5 source.asciidoc
           end
         end
 
+        infiles = []
         # 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 == '-' || (file.start_with? '-')
+            if file.start_with? '-'
               # warn, but don't panic; we may have enough to proceed, so we won't force a failure
               $stderr.puts %(asciidoctor: WARNING: extra arguments detected (unparsed arguments: '#{args.join "', '"}') or incorrect usage of stdin)
+            elsif ::File.file? file
+              infiles << file
+            # NOTE only attempt to glob if file is not found
             else
-              if ::File.file? file
+              # Tilt backslashes in Windows paths the Ruby-friendly way
+              if ::File::ALT_SEPARATOR == RS && (file.include? RS)
+                file = file.tr RS, FS
+              end
+              if (matches = ::Dir.glob file).empty?
+                # NOTE if no matches, assume it's just a missing file and proceed
                 infiles << file
-              # NOTE only attempt to glob if file is not found
               else
-                # Tilt backslashes in Windows paths the Ruby-friendly way
-                if ::File::ALT_SEPARATOR == RS && (file.include? RS)
-                  file = file.tr RS, FS
-                end
-                if (matches = ::Dir.glob file).empty?
-                  # NOTE if no matches, assume it's just a missing file and proceed
-                  infiles << file
-                else
-                  infiles.concat matches
-                end
+                infiles.concat matches
               end
             end
           end
@@ -236,16 +249,16 @@ Example: asciidoctor -b html5 source.asciidoc
 
         self[:input_files] = infiles
 
-        self.delete(:attributes) if self[:attributes].empty?
+        delete :attributes if self[:attributes].empty?
 
         if self[:template_dirs]
           begin
-            require 'tilt' unless defined? ::Tilt::VERSION
+            require 'tilt' unless defined? ::Tilt.new
           rescue ::LoadError
             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
@@ -253,19 +266,19 @@ Example: asciidoctor -b html5 source.asciidoc
         end
 
         if (load_paths = self[:load_paths])
-          (self[:load_paths] = load_paths.uniq).reverse_each do |path|
-            $:.unshift ::File.expand_path(path)
-          end
+          load_paths.uniq!
+          load_paths.reverse_each {|path| $:.unshift ::File.expand_path path }
         end
 
         if (requires = self[:requires])
-          (self[:requires] = requires.uniq).each do |path|
+          requires.uniq!
+          requires.each do |path|
             begin
               require path
             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
@@ -277,23 +290,21 @@ Example: asciidoctor -b html5 source.asciidoc
       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
 
       def print_version os = $stdout
         os.puts %(Asciidoctor #{::Asciidoctor::VERSION} [https://asciidoctor.org])
-        if ::RUBY_MIN_VERSION_1_9
-          encoding_info = { 'lc' => 'locale', 'fs' => 'filesystem', 'in' => 'internal', 'ex' => 'external' }.map do |k, v|
-            %(#{k}:#{v == 'internal' ? (::File.open(__FILE__) {|f| f.getc }).encoding : (::Encoding.find v)})
-          end
-          os.puts %(Runtime Environment (#{::RUBY_DESCRIPTION}) (#{encoding_info.join ' '}))
-        else
-          os.puts %(Runtime Environment (#{::RUBY_DESCRIPTION}))
+        encoding_info = { 'lc' => 'locale', 'fs' => 'filesystem', 'in' => 'internal', 'ex' => 'external' }.map do |k, v|
+          %(#{k}:#{v == 'internal' ? (::File.open(__FILE__) {|f| f.getc.encoding }) : (::Encoding.find v)})
         end
+        os.puts %(Runtime Environment (#{::RUBY_DESCRIPTION}) (#{encoding_info.join ' '}))
         0
       end
     end

data/lib/asciidoctor/cli.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'optparse'
-require 'asciidoctor/cli/options'
-require 'asciidoctor/cli/invoker'
+require_relative 'cli/options'
+require_relative 'cli/invoker'

data/lib/asciidoctor/convert.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+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