asciidoctor 1.5.6.2 → 1.5.7

data/lib/asciidoctor.rb

@@ -13,6 +13,7 @@ if RUBY_ENGINE == 'opal'
   require 'asciidoctor/js'
 else
   autoload :Base64, 'base64'
+  autoload :URI, 'uri'
   autoload :OpenURI, 'open-uri'
   autoload :StringScanner, 'strscan'
 end
@@ -20,6 +21,8 @@ end
 # ideally we should use require_relative instead of modifying the LOAD_PATH
 $:.unshift File.dirname __FILE__
 
+require 'asciidoctor/logging'
+
 # Public: Methods for parsing AsciiDoc input files and converting documents
 # using eRuby templates.
 #
@@ -170,6 +173,11 @@ module Asciidoctor
     # Compliance value: false
     define :shorthand_property_syntax, true
 
+    # Asciidoctor will attempt to resolve the target of a cross reference by
+    # matching its reference text (reftext or title) (e.g., <<Section Title>>)
+    # Compliance value: false
+    define :natural_xrefs, true
+
     # Asciidoctor will start counting at the following number
     # when creating a unique id when there is a conflict
     # Compliance value: 2
@@ -225,6 +233,9 @@ module Asciidoctor
   # String for matching tab character
   TAB = "\t"
 
+  # Maximum integer value for "boundless" operations; equal to MAX_SAFE_INTEGER in JavaScript
+  MAX_INT = 9007199254740991
+
   # The default document type
   # Can influence markup generated by the converters
   DEFAULT_DOCTYPE = 'article'
@@ -259,10 +270,10 @@ module Asciidoctor
 
   # Set of file extensions recognized as AsciiDoc documents (stored as a truth hash)
   ASCIIDOC_EXTENSIONS = {
-    '.asciidoc' => true,
     '.adoc' => true,
-    '.ad' => true,
+    '.asciidoc' => true,
     '.asc' => true,
+    '.ad' => true,
     # TODO .txt should be deprecated
     '.txt' => true
   }
@@ -281,7 +292,7 @@ module Asciidoctor
 
   CALLOUT_LIST_HEADS = ['<', '1', '2', '3', '4', '5', '6', '7', '8', '9', '0'].to_set
 
-  PARAGRAPH_STYLES = ['comment', 'example', 'literal', 'listing', 'normal', 'pass', 'quote', 'sidebar', 'source', 'verse', 'abstract', 'partintro'].to_set
+  PARAGRAPH_STYLES = ['comment', 'example', 'literal', 'listing', 'normal', 'open', 'pass', 'quote', 'sidebar', 'source', 'verse', 'abstract', 'partintro'].to_set
 
   VERBATIM_STYLES = ['literal', 'listing', 'source', 'verse'].to_set
 
@@ -345,6 +356,8 @@ module Asciidoctor
 
   LINE_CONTINUATION_LEGACY = ' +'
 
+  MATHJAX_VERSION = '2.7.4'
+
   BLOCK_MATH_DELIMITERS = {
     :asciimath => ['\$', '\$'],
     :latexmath => ['\[', '\]'],
@@ -355,21 +368,18 @@ module Asciidoctor
     :latexmath => ['\(', '\)'],
   }
 
+  (STEM_TYPE_ALIASES = {
+    'latexmath' => 'latexmath',
+    'latex' => 'latexmath',
+    'tex' => 'latexmath'
+  }).default = 'asciimath'
+
+  FONT_AWESOME_VERSION = '4.7.0'
+
   # attributes which be changed within the content of the document (but not
   # header) because it has semantic meaning; ex. sectnums
   FLEXIBLE_ATTRIBUTES = ['sectnums']
 
-  # map of file extension to comment affixes for languages that only support circumfix comments
-  CIRCUMFIX_COMMENTS = {
-    ['/*', '*/'] => ['.css'],
-    ['(*', '*)'] => ['.ml', '.mli', '.nb'],
-    ['<!--', '-->'] => ['.html', '.xhtml', '.xml', '.xsl'],
-    ['<%--', '--%>'] => ['.asp', '.jsp']
-  }.inject({}) {|accum, (affixes, exts)|
-    exts.each {|ext| accum[ext] = { :prefix => affixes[0], :suffix => affixes[-1] } }
-    accum
-  }
-
   # A collection of regular expressions used by the parser.
   #
   # NOTE: The following pattern, which appears frequently, captures the
@@ -485,7 +495,7 @@ module Asciidoctor
     #   include::chapter1.ad[]
     #   include::example.txt[lines=1;2;5..10]
     #
-    IncludeDirectiveRx = /^(\\)?include::([^\[][^\[]*)\[(.*)\]$/
+    IncludeDirectiveRx = /^(\\)?include::([^\[][^\[]*)\[(.+)?\]$/
 
     # Matches a trailing tag directive in an include file.
     #
@@ -498,7 +508,7 @@ module Asciidoctor
     #     log(e);
     #   }
     #   // end::try-catch[]
-    TagDirectiveRx = /\b(?:tag|(end))::(\S+)\[\]$/
+    TagDirectiveRx = /\b(?:tag|(e)nd)::(\S+?)\[\][\n \r]/
 
     ## Attribute entries and references
 
@@ -515,10 +525,10 @@ module Asciidoctor
     #                collapsing the line breaks and indentation to \
     #                a single space.
     #
-    AttributeEntryRx = /^:(!?\w.*?):(?:[ \t]+(.*))?$/
+    AttributeEntryRx = /^:(!?#{CG_WORD}[^:]*):(?:[ \t]+(.*))?$/
 
     # Matches invalid characters in an attribute name.
-    InvalidAttributeNameCharsRx = /[^\w\-]/
+    InvalidAttributeNameCharsRx = /[^#{CC_WORD}-]/
 
     # Matches a pass inline macro that surrounds the value of an attribute
     # entry once it has been parsed.
@@ -544,7 +554,7 @@ module Asciidoctor
     #   {set:foo:bar}
     #   {set:name!}
     #
-    AttributeReferenceRx = /(\\)?\{(\w+[-\w]*|(set|counter2?):.+?)(\\)?\}/
+    AttributeReferenceRx = /(\\)?\{(#{CG_WORD}+[-#{CC_WORD}]*|(set|counter2?):.+?)(\\)?\}/
 
     ## Paragraphs and delimited blocks
 
@@ -583,7 +593,7 @@ module Asciidoctor
     #
     #   .Title goes here
     #
-    BlockTitleRx = /^\.([^ \t.].*)$/
+    BlockTitleRx = /^\.(\.?[^ \t.].*)$/
 
     # Matches an admonition label at the start of a paragraph.
     #
@@ -650,26 +660,17 @@ module Asciidoctor
     #
     InlineSectionAnchorRx = / (\\)?\[\[([#{CC_ALPHA}_:][#{CC_WORD}:.-]*)(?:, *(.+))?\]\]$/
 
-    # Matches invalid characters in a section id.
+    # Matches invalid ID characters in a section title.
     #
-    # NOTE uppercase chars are not included since the expression is used on a lowercased string
-    InvalidSectionIdCharsRx = /&(?:[a-z][a-z]+\d{0,2}|#\d\d\d{0,4}|#x[\da-f][\da-f][\da-f]{0,3});|[^#{CC_WORD}]+?/
-
-    # Matches the block style used to designate a discrete (aka free-floating) heading.
-    #
-    # Examples
-    #
-    #   [discrete]
-    #   = Discrete Heading
-    #
-    DiscreteHeadingStyleRx = /^(?:discrete|float)\b/
+    # NOTE uppercase chars not included since expression is only run on a lowercase string
+    InvalidSectionIdCharsRx = /<[^>]+>|&(?:[a-z][a-z]+\d{0,2}|#\d\d\d{0,4}|#x[\da-f][\da-f][\da-f]{0,3});|[^ #{CC_WORD}\-.]+?/
 
     ## Lists
 
     # Detects the start of any list item.
     #
     # NOTE we only have to check as far as the blank character because we know it means non-whitespace follows.
-    AnyListRx = /^(?:[ \t]*(?:-|\*\*{0,4}|\.\.{0,4}|\u2022\u2022{0,4}|\d+\.|[a-zA-Z]\.|[IVXivx]+\))[ \t]|[ \t]*.*?(?::{2,4}|;;)(?:$|[ \t])|<?\d+>[ \t])/
+    AnyListRx = /^(?:[ \t]*(?:-|\*\*{0,4}|\.\.{0,4}|\u2022\u2022{0,4}|\d+\.|[a-zA-Z]\.|[IVXivx]+\))[ \t]|[ \t]*.*?(?::::{0,2}|;;)(?:$|[ \t])|<?\d+>[ \t])/
 
     # Matches an unordered list item (one level for hyphens, up to 5 levels for asterisks).
     #
@@ -712,35 +713,34 @@ module Asciidoctor
     # Examples
     #
     #   foo::
-    #   foo:::
-    #   foo::::
-    #   foo;;
+    #   bar:::
+    #   baz::::
+    #   blah;;
     #
-    #   # the term can be followed by a description on the same line...
+    #   # the term may be followed by a description on the same line...
     #
-    #   foo:: That which precedes 'bar' (see also, <<bar>>)
+    #   foo:: The metasyntactic variable that commonly accompanies 'bar' (see also, <<bar>>).
     #
-    #   # ...or on a separate line (optionally indented)
+    #   # ...or on a separate line, which may optionally be indented
     #
     #   foo::
-    #     That which precedes 'bar' (see also, <<bar>>)
+    #     The metasyntactic variable that commonly accompanies 'bar' (see also, <<bar>>).
     #
-    #   # the term or description may be an attribute reference
+    #   # attribute references may be used in both the term and the description
     #
-    #   {foo_term}:: {foo_def}
+    #   {foo-term}:: {foo-desc}
     #
+    # NOTE we know trailing (.*) will match at least one character because we strip trailing spaces
     # NOTE negative match for comment line is intentional since that isn't handled when looking for next list item
     # TODO check for line comment when scanning lines instead of in regex
-    #
-    DescriptionListRx = %r(^(?!//)[ \t]*(.*?)(:{2,4}|;;)(?:[ \t]+(.*))?$)
+    DescriptionListRx = %r(^(?!//)[ \t]*(.*?)(:::{0,2}|;;)(?:$|[ \t]+(.*)$))
 
     # Matches a sibling description list item (which does not include the type in the key).
     DescriptionListSiblingRx = {
-      # (?:.*?[^:])? - a non-capturing group which grabs longest sequence of characters that doesn't end w/ colon
-      '::' => %r(^(?!//)[ \t]*((?:.*[^:])?)(::)(?:[ \t]+(.*))?$),
-      ':::' => %r(^(?!//)[ \t]*((?:.*[^:])?)(:::)(?:[ \t]+(.*))?$),
-      '::::' => %r(^(?!//)[ \t]*((?:.*[^:])?)(::::)(?:[ \t]+(.*))?$),
-      ';;' => %r(^(?!//)[ \t]*(.*)(;;)(?:[ \t]+(.*))?$)
+      '::' => %r(^(?!//)[ \t]*(.*[^:]|)(::)(?:$|[ \t]+(.*)$)),
+      ':::' => %r(^(?!//)[ \t]*(.*[^:]|)(:::)(?:$|[ \t]+(.*)$)),
+      '::::' => %r(^(?!//)[ \t]*(.*[^:]|)(::::)(?:$|[ \t]+(.*)$)),
+      ';;' => %r(^(?!//)[ \t]*(.*?)(;;)(?:$|[ \t]+(.*)$))
     }
 
     # Matches a callout list item.
@@ -787,7 +787,7 @@ module Asciidoctor
     #
     #   1*h,2*,^3e
     #
-    ColumnSpecRx = /^(?:(\d+)\*)?([<^>](?:\.[<^>]?)?|(?:[<^>]?\.)?[<^>])?(\d+%?)?([a-z])?$/
+    ColumnSpecRx = /^(?:(\d+)\*)?([<^>](?:\.[<^>]?)?|(?:[<^>]?\.)?[<^>])?(\d+%?|~)?([a-z])?$/
 
     # Parses the start and end of a cell spec (i.e., cellspec) for a table.
     #
@@ -809,7 +809,7 @@ module Asciidoctor
     #
     #--
     # NOTE we've relaxed the match for target to accomodate the short format (e.g., name::[attrlist])
-    CustomBlockMacroRx = /^(#{CG_WORD}+)::(|\S|\S.*?\S)\[(.*)\]$/
+    CustomBlockMacroRx = /^(#{CG_WORD}+)::(|\S|\S.*?\S)\[(.+)?\]$/
 
     # Matches an image, video or audio block macro.
     #
@@ -818,7 +818,7 @@ module Asciidoctor
     #   image::filename.png[Caption]
     #   video::http://youtube.com/12345[Cats vs Dogs]
     #
-    BlockMediaMacroRx = /^(image|video|audio)::(\S|\S.*?\S)\[(.*)\]$/
+    BlockMediaMacroRx = /^(image|video|audio)::(\S|\S.*?\S)\[(.+)?\]$/
 
     # Matches the TOC block macro.
     #
@@ -827,7 +827,7 @@ module Asciidoctor
     #   toc::[]
     #   toc::[levels=2]
     #
-    BlockTocMacroRx = /^toc::\[(.*)\]$/
+    BlockTocMacroRx = /^toc::\[(.+)?\]$/
 
     ## Inline macros
 
@@ -845,6 +845,9 @@ module Asciidoctor
     # Scans for a non-escaped anchor (i.e., id + optional reference text) in the flow of text.
     InlineAnchorScanRx = /(?:^|[^\\\[])\[\[([#{CC_ALPHA}_:][#{CC_WORD}:.-]*)(?:, *(.+?))?\]\]|(?:^|[^\\])anchor:([#{CC_ALPHA}_:][#{CC_WORD}:.-]*)\[(?:\]|(.*?[^\\])\])/
 
+    # Scans for a leading, non-escaped anchor (i.e., id + optional reference text).
+    LeadingInlineAnchorRx = /^\[\[([#{CC_ALPHA}_:][#{CC_WORD}:.-]*)(?:, *(.+?))?\]\]/
+
     # Matches a bibliography anchor at the start of the list item text (in a bibliography list).
     #
     # Examples
@@ -857,16 +860,18 @@ module Asciidoctor
     #
     #   doc.writer@example.com
     #
-    EmailInlineRx = %r(([\\>:/])?#{CG_WORD}[#{CC_WORD}.%+-]*@#{CG_ALNUM}[#{CC_ALNUM}.-]*\.#{CG_ALPHA}{2,4}\b)
+    InlineEmailRx = %r(([\\>:/])?#{CG_WORD}[#{CC_WORD}.%+-]*@#{CG_ALNUM}[#{CC_ALNUM}.-]*\.#{CG_ALPHA}{2,4}\b)
 
     # Matches an inline footnote macro, which is allowed to span multiple lines.
     #
     # Examples
-    #   footnote:[text]
-    #   footnoteref:[id,text]
-    #   footnoteref:[id]
+    #   footnote:[text] (not referenceable)
+    #   footnote:id[text] (referenceable)
+    #   footnote:id[] (reference)
+    #   footnoteref:[id,text] (legacy)
+    #   footnoteref:[id] (legacy)
     #
-    InlineFootnoteMacroRx = /\\?(footnote(?:ref)?):\[(#{CC_ALL}*?[^\\])\]/m
+    InlineFootnoteMacroRx = /\\?footnote(?:(ref):|:([\w-]+)?)\[(?:|(#{CC_ALL}*?[^\\]))\]/m
 
     # Matches an image or icon inline macro.
     #
@@ -913,7 +918,7 @@ module Asciidoctor
     #   link:https://github.com[]
     #
     # FIXME revisit! the main issue is we need different rules for implicit vs explicit
-    LinkInlineRx = %r((^|link:|#{CG_BLANK}|&lt;|[>\(\)\[\];])(\\?(?:https?|file|ftp|irc)://[^\s\[\]<]*[^\s.,\[\]<])(?:\[(|#{CC_ALL}*?[^\\])\])?)m
+    InlineLinkRx = %r((^|link:|#{CG_BLANK}|&lt;|[>\(\)\[\];])(\\?(?:https?|file|ftp|irc)://[^\s\[\]<]*[^\s.,\[\]<])(?:\[(|#{CC_ALL}*?[^\\])\])?)m
 
     # Match a link or e-mail inline macro.
     #
@@ -955,9 +960,9 @@ module Asciidoctor
     #
     #   "File > New..."
     #
-    MenuInlineRx = /\\?"([#{CC_WORD}&][^"]*?[ \n]+&gt;[ \n]+[^"]*)"/
+    InlineMenuRx = /\\?"([#{CC_WORD}&][^"]*?[ \n]+&gt;[ \n]+[^"]*)"/
 
-    # Matches an inline passthrough value, which may span multiple lines.
+    # Matches an inline passthrough, which may span multiple lines.
     #
     # Examples
     #
@@ -965,11 +970,20 @@ module Asciidoctor
     #   `text` (compat)
     #
     # NOTE we always capture the attributes so we know when to use compatible (i.e., legacy) behavior
-    PassInlineRx = {
+    InlinePassRx = {
       false => ['+', '`', /(^|[^#{CC_WORD};:])(?:\[([^\]]+)\])?(\\?(\+|`)(\S|\S#{CC_ALL}*?\S)\4)(?!#{CG_WORD})/m],
       true  => ['`', nil, /(^|[^`#{CC_WORD}])(?:\[([^\]]+)\])?(\\?(`)([^`\s]|[^`\s]#{CC_ALL}*?\S)\4)(?![`#{CC_WORD}])/m]
     }
 
+    # Matches an inline plus passthrough spanning multiple lines, but only when it occurs directly
+    # inside constrained monospaced formatting in non-compat mode.
+    #
+    # Examples
+    #
+    #   +text+
+    #
+    SinglePlusInlinePassRx = /^(\\)?\+(\S|\S#{CC_ALL}*?\S)\+$/m
+
     # Matches several variants of the passthrough inline macro, which may span multiple lines.
     #
     # Examples
@@ -1257,8 +1271,9 @@ module Asciidoctor
   # Public: Parse the AsciiDoc source input into a {Document}
   #
   # Accepts input as an IO (or StringIO), String or String Array object. If the
-  # input is a File, information about the file is stored in attributes on the
-  # Document object.
+  # 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.
   #
   # input   - the AsciiDoc source as a IO, String or Array.
   # options - a String, Array or Hash of options to control processing (default: {})
@@ -1268,10 +1283,15 @@ module Asciidoctor
   # Returns the Document
   def load input, options = {}
     options = options.dup
+
     if (timings = options[:timings])
       timings.start :read
     end
 
+    if (logger = options[:logger]) && logger != LoggerManager.logger
+      LoggerManager.logger = logger
+    end
+
     if !(attrs = options[:attributes])
       attrs = {}
     elsif ::Hash === attrs || (::RUBY_ENGINE_JRUBY && ::Java::JavaUtil::Map === attrs)
@@ -1363,10 +1383,6 @@ module Asciidoctor
 
   # Public: Parse the contents of the AsciiDoc source file into an Asciidoctor::Document
   #
-  # Accepts input as an IO, String or String Array object. If the
-  # input is a File, information about the file is stored in
-  # attributes on the Document.
-  #
   # 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.
@@ -1374,17 +1390,18 @@ module Asciidoctor
   #
   # Returns the Asciidoctor::Document
   def load_file filename, options = {}
-    ::File.open(filename) {|file| self.load file, options }
+    ::File.open(filename, 'rb') {|file| self.load file, options }
   end
 
   # Public: Parse the AsciiDoc source input into an Asciidoctor::Document and
   # convert it to the specified backend format.
   #
-  # Accepts input as an IO, String or String Array object. If the
-  # input is a File, information about the file is stored in
-  # attributes on the Document.
+  # 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 :in_place option is true, and the input is a File, the output is
+  # 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
@@ -1412,7 +1429,6 @@ module Asciidoctor
     to_file = options.delete(:to_file)
     to_dir = options.delete(:to_dir)
     mkdirs = options.delete(:mkdirs) || false
-    timings = options[:timings]
 
     case to_file
     when true, nil
@@ -1429,7 +1445,7 @@ module Asciidoctor
       return self.load input, options
     else
       write_to_same_dir = false
-      write_to_target = (stream_output = to_file.respond_to? :write) ? false : to_file
+      write_to_target = (stream_output = to_file.respond_to? :write) ? false : (options[:to_file] = to_file)
     end
 
     unless options.key? :header_footer
@@ -1443,17 +1459,17 @@ module Asciidoctor
     elsif write_to_target
       if to_dir
         if to_file
-          options[:to_dir] = ::File.expand_path ::File.join to_dir, to_file, '..'
+          options[:to_dir] = ::File.dirname ::File.expand_path ::File.join to_dir, to_file
         else
           options[:to_dir] = ::File.expand_path to_dir
         end
       elsif to_file
-        options[:to_dir] = ::File.expand_path to_file, '..'
+        options[:to_dir] = ::File.dirname ::File.expand_path to_file
       end
-    else
-      options[:to_dir] = nil
     end
 
+    # NOTE :to_dir is always set when outputting to a file
+    # NOTE :to_file option only passed if assigned an explicit path
     doc = self.load input, options
 
     if write_to_same_dir # write to file in same directory
@@ -1462,7 +1478,7 @@ module Asciidoctor
         raise ::IOError, %(input file and output file cannot be the same: #{outfile})
       end
     elsif write_to_target # write to explicit file or directory
-      working_dir = (options.key? :base_dir) ? (::File.expand_path options[:base_dir]) : (::File.expand_path ::Dir.pwd)
+      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
@@ -1484,28 +1500,22 @@ module Asciidoctor
         raise ::IOError, %(input file and output file cannot be the same: #{outfile})
       end
 
-      unless ::File.directory? outdir
-        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})
-        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
 
-    timings.start :convert if timings
     opts = outfile && !stream_output ? { 'outfile' => outfile, 'outdir' => outdir } : {}
     output = doc.convert opts
-    timings.record :convert if timings
 
     if outfile
-      timings.start :write if timings
       doc.write output, outfile
-      timings.record :write if timings
 
       # NOTE document cannot control this behavior if safe >= SafeMode::SERVER
       # NOTE skip if stylesdir is a URI
@@ -1525,7 +1535,11 @@ module Asciidoctor
         copy_pygments_stylesheet = (doc.attr? 'source-highlighter', 'pygments') && (doc.attr 'pygments-css', 'class') == 'class'
         if copy_asciidoctor_stylesheet || copy_user_stylesheet || copy_coderay_stylesheet || copy_pygments_stylesheet
           stylesoutdir = doc.normalize_system_path(stylesdir, outdir, doc.safe >= SafeMode::SAFE ? outdir : nil)
-          Helpers.mkdir_p stylesoutdir if mkdirs
+          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
@@ -1572,7 +1586,7 @@ module Asciidoctor
   # 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| self.convert file, options }
+    ::File.open(filename, 'rb') {|file| self.convert file, options }
   end
 
   # Alias render_file to convert_file to maintain backwards compatibility