asciidoctor 0.1.4 → 1.5.0

data/lib/asciidoctor/converter/template.rb

@@ -0,0 +1,296 @@
+module Asciidoctor
+  # A {Converter} implementation that uses templates composed in template
+  # languages supported by {https://github.com/rtomayko/tilt Tilt} to convert
+  # {AbstractNode} objects from a parsed AsciiDoc document tree to the backend
+  # format.
+  #
+  # The converter scans the provided directories for template files that are
+  # supported by Tilt. If an engine name (e.g., "slim") is specified in the
+  # options Hash passed to the constructor, the scan is limited to template
+  # files that have a matching extension (e.g., ".slim"). The scanner trims any
+  # extensions from the basename of the file and uses the resulting name as the
+  # key under which to store the template. When the {Converter#convert} method
+  # is invoked, the transform argument is used to select the template from this
+  # table and use it to convert the node.
+  #
+  # For example, the template file "path/to/templates/paragraph.html.slim" will
+  # be registered as the "paragraph" transform. The template would then be used
+  # to convert a paragraph {Block} object from the parsed AsciiDoc tree to an
+  # HTML backend format (e.g., "html5").
+  #
+  # As an optimization, scan results and templates are cached for the lifetime
+  # of the Ruby process. If the {https://rubygems.org/gems/thread_safe
+  # thread_safe} gem is installed, these caches are guaranteed to be thread
+  # safe. If this gem is not present, a warning is issued.
+  class Converter::TemplateConverter < Converter::Base
+    DEFAULT_ENGINE_OPTIONS = {
+      :erb =>  { :trim => '<' },
+      # TODO line 466 of haml/compiler.rb sorts the attributes; file an issue to make this configurable
+      # NOTE AsciiDoc syntax expects HTML/XML output to use double quotes around attribute values
+      :haml => { :format => :xhtml, :attr_wrapper => '"', :ugly => true, :escape_attrs => false },
+      :slim => { :disable_escape => true, :sort_attrs => false, :pretty => false }
+    }
+
+    # QUESTION are we handling how we load the thread_safe support correctly?
+    begin
+      require 'thread_safe' unless defined? ::ThreadSafe
+      @caches = { :scans => ::ThreadSafe::Cache.new, :templates => ::ThreadSafe::Cache.new }
+    rescue ::LoadError
+      @caches = {}
+      # FIXME perhaps only warn if the cache option is enabled?
+      warn 'asciidoctor: WARNING: gem \'thread_safe\' is not installed. This gem recommended when using custom backend templates.'
+    end
+
+    def self.caches
+      @caches
+    end
+
+    def self.clear_caches
+      @caches[:scans].clear if @caches[:scans]
+      @caches[:templates].clear if @caches[:templates]
+    end
+
+    def initialize backend, template_dirs, opts = {}
+      @backend = backend
+      @templates = {}
+      @template_dirs = template_dirs
+      @eruby = opts[:eruby]
+      @engine = opts[:template_engine]
+      @engine_options = DEFAULT_ENGINE_OPTIONS.inject({}) do |accum, (engine, default_opts)|
+        accum[engine] = default_opts.dup
+        accum
+      end
+      if (overrides = opts[:template_engine_options])
+        overrides.each do |engine, override_opts|
+          (@engine_options[engine] ||= {}).update override_opts
+        end
+      end
+      @engine_options[:haml][:format] = @engine_options[:slim][:format] = :html5 if opts[:htmlsyntax] == 'html'
+      case opts[:template_cache]
+      when true
+        @caches = self.class.caches
+      when ::Hash
+        @caches = opts[:template_cache]
+      else
+        @caches = {}
+      end
+      scan
+      #create_handlers
+    end
+
+=begin
+    # Public: Called when this converter is added to a composite converter.
+    def composed parent
+      # TODO set the backend info determined during the scan
+    end
+=end
+
+    # Internal: Scans the template directories specified in the constructor for Tilt-supported
+    # templates, loads the templates and stores the in a Hash that is accessible via the
+    # {TemplateConverter#templates} method.
+    #
+    # Returns nothing
+    def scan
+      path_resolver = PathResolver.new
+      backend = @backend
+      engine = @engine
+      @template_dirs.each do |template_dir|
+        # FIXME need to think about safe mode restrictions here
+        template_dir = path_resolver.system_path template_dir, nil
+        # NOTE last matching template wins for template name if no engine is given
+        file_pattern = '*'
+        if engine
+          file_pattern = %(*.#{engine})
+          # example: templates/haml
+          if ::File.directory?(engine_dir = (::File.join template_dir, engine))
+            template_dir = engine_dir
+          end
+        end
+
+        # example: templates/html5 or templates/haml/html5
+        if ::File.directory?(backend_dir = (::File.join template_dir, backend))
+          template_dir = backend_dir
+        end
+
+        pattern = ::File.join template_dir, file_pattern
+
+        if (scan_cache = @caches[:scans])
+          template_cache = @caches[:templates]
+          unless (templates = scan_cache[pattern])
+            templates = (scan_cache[pattern] = (scan_dir template_dir, pattern, template_cache))
+          end
+          templates.each do |name, template|
+            @templates[name] = template_cache[template.file] = template
+          end
+        else
+          @templates.update scan_dir(template_dir, pattern, @caches[:templates])
+        end
+        nil
+      end
+    end
+
+=begin
+    # Internal: Creates convert methods (e.g., inline_anchor) that delegate to the discovered templates.
+    #
+    # Returns nothing
+    def create_handlers
+      @templates.each do |name, template|
+        create_handler name, template
+      end
+      nil
+    end
+
+    # Internal: Creates a convert method for the specified name that delegates to the specified template.
+    # 
+    # Returns nothing
+    def create_handler name, template
+      metaclass = class << self; self; end
+      if name == 'document'
+        metaclass.send :define_method, name do |node|
+          (template.render node).strip
+        end
+      else
+        metaclass.send :define_method, name do |node|
+          (template.render node).chomp
+        end
+      end
+    end
+=end
+
+    # Public: Convert an {AbstractNode} to the backend format using the named template.
+    #
+    # Looks for a template that matches the value of the
+    # {AbstractNode#node_name} property if a template name is not specified.
+    #
+    # node          - the AbstractNode to convert
+    # template_name - the String name of the template to use, or the value of
+    #                 the node_name property on the node if a template name is
+    #                 not specified. (optional, default: nil)
+    #
+    # Returns the [String] result from rendering the template
+    def convert node, template_name = nil
+      template_name ||= node.node_name
+      unless (template = @templates[template_name])
+        raise %(Could not find a custom template to handle transform: #{template_name})
+      end
+      if template_name == 'document'
+        (template.render node).strip
+      else
+        (template.render node).chomp
+      end
+    end
+
+    # Public: Convert an {AbstractNode} using the named template with the
+    # additional options provided.
+    #
+    # Looks for a template that matches the value of the
+    # {AbstractNode#node_name} property if a template name is not specified.
+    #
+    # node          - the AbstractNode to convert
+    # template_name - the String name of the template to use, or the value of
+    #                 the node_name property on the node if a template name is
+    #                 not specified. (optional, default: nil)
+    # opts          - an optional Hash that is passed as local variables to the
+    #                 template. (optional, default: {})
+    #
+    # Returns the [String] result from rendering the template
+    def convert_with_options node, template_name = nil, opts = {}
+      template_name ||= node.node_name
+      unless (template = @templates[template_name])
+        raise %(Could not find a custom template to handle transform: #{template_name})
+      end
+      (template.render node, opts).chomp
+    end
+
+    # Public: Checks whether there is a Tilt template registered with the specified name.
+    #
+    # name - the String template name
+    #
+    # Returns a [Boolean] that indicates whether a Tilt template is registered for the
+    # specified template name.
+    def handles? name
+      @templates.key? name
+    end
+
+    # Public: Retrieves the templates that this converter manages.
+    #
+    # Returns a [Hash] of Tilt template objects keyed by template name.
+    def templates
+      @templates.dup.freeze
+    end
+
+    # Public: Registers a Tilt template with this converter.
+    #
+    # name     - the String template name
+    # template - the Tilt template object to register
+    #
+    # Returns the Tilt template object
+    def register name, template
+      @templates[name] = if (template_cache = @caches[:templates])
+        template_cache[template.file] = template
+      else
+        template
+      end
+      #create_handler name, template
+    end
+
+    # Internal: Scan the specified directory for template files matching pattern and instantiate
+    # a Tilt template for each matched file.
+    #
+    # Returns the scan result as a [Hash]
+    def scan_dir template_dir, pattern, template_cache = nil
+      result = {}
+      eruby_loaded = nil
+      # Grab the files in the top level of the directory (do not recurse)
+      ::Dir.glob(pattern).select {|match| ::File.file? match }.each do |file|
+        if (basename = ::File.basename file) == 'helpers.rb' || (path_segments = basename.split '.').size < 2
+          next
+        end
+        # TODO we could derive the basebackend from the minor extension of the template file
+        #name, *rest, ext_name = *path_segments # this form only works in Ruby >= 1.9
+        name = path_segments[0]
+        if name == 'block_ruler'
+          name = 'thematic_break'
+        elsif name.start_with? 'block_'
+          name = name[6..-1]
+        end
+        ext_name = path_segments[-1]
+        template_class = ::Tilt
+        extra_engine_options = {}
+        if ext_name == 'slim'
+          # slim doesn't get loaded by Tilt, so we have to load it explicitly
+          Helpers.require_library 'slim' unless defined? ::Slim
+        elsif ext_name == 'erb'
+          template_class, extra_engine_options = (eruby_loaded ||= load_eruby @eruby)
+        end
+        next unless ::Tilt.registered? ext_name
+        unless template_cache && (template = template_cache[file])
+          template = template_class.new file, 1, (@engine_options[ext_name.to_sym] || {}).merge(extra_engine_options)
+        end
+        result[name] = template
+      end
+      if ::File.file?(helpers = (::File.join template_dir, 'helpers.rb'))
+        require helpers
+      end
+      result
+    end
+
+    # Internal: Load the eRuby implementation
+    #
+    # name - the String name of the eRuby implementation
+    #
+    # Returns an [Array] containing the Tilt template Class for the eRuby implementation
+    # and a Hash of additional options to pass to the initializer
+    def load_eruby name
+      if !name || name == 'erb'
+        require 'erb' unless defined? ::ERB
+        [::Tilt::ERBTemplate, {}]
+      elsif name == 'erubis'
+        Helpers.require_library 'erubis' unless defined? ::Erubis::FastEruby
+        [::Tilt::ErubisTemplate, { :engine_class => ::Erubis::FastEruby }]
+      else
+        raise ::ArgumentError, %(Unknown ERB implementation: #{name})
+      end
+    end
+  end
+end

data/lib/asciidoctor/core_ext.rb

@@ -0,0 +1,7 @@
+require 'asciidoctor/core_ext/object/nil_or_empty'
+unless RUBY_ENGINE == 'opal'
+  unless RUBY_MIN_VERSION_1_9
+    require 'asciidoctor/core_ext/string/chr'
+    require 'asciidoctor/core_ext/symbol/length'
+  end
+end

data/lib/asciidoctor/core_ext/object/nil_or_empty.rb

@@ -0,0 +1,23 @@
+# A core library extension that defines the method nil_or_empty? as an alias to
+# optimize checks for nil? or empty? on common object types such as NilClass,
+# String, Array and Hash.
+
+class NilClass
+  alias :nil_or_empty? :nil? unless respond_to? :nil_or_empty?
+end
+
+class String
+  alias :nil_or_empty? :empty? unless respond_to? :nil_or_empty?
+end
+
+class Array
+  alias :nil_or_empty? :empty? unless respond_to? :nil_or_empty?
+end
+
+class Hash
+  alias :nil_or_empty? :empty? unless respond_to? :nil_or_empty?
+end
+
+class Numeric
+  alias :nil_or_empty? :nil? unless respond_to? :nil_or_empty?
+end

data/lib/asciidoctor/core_ext/string/chr.rb

@@ -0,0 +1,6 @@
+# Educate Ruby 1.8.7 about the String#chr method.
+class String
+  def chr
+    self[0..0]
+  end unless respond_to? :chr
+end

data/lib/asciidoctor/core_ext/symbol/length.rb

@@ -0,0 +1,6 @@
+# Educate Ruby 1.8.7 about the Symbol#length method.
+class Symbol
+  def length
+    to_s.length
+  end unless respond_to? :length
+end

data/lib/asciidoctor/document.rb

@@ -1,6 +1,5 @@
 module Asciidoctor
-# Public: Methods for parsing Asciidoc documents and rendering them
-# using erb templates.
+# Public: Methods for parsing and converting AsciiDoc documents.
 #
 # There are several strategies for getting the title of the document:
 #
@@ -16,21 +15,55 @@ module Asciidoctor
 #
 # notitle  - The h1 heading should not be shown
 # noheader - The header block (h1 heading, author, revision info) should not be shown
+# nofooter - the footer block should not be shown
 class Document < AbstractBlock
 
-  Footnote = Struct.new(:index, :id, :text)
-  AttributeEntry = Struct.new(:name, :value, :negate) do
-    def initialize(name, value, negate = nil)
-      super(name, value, negate.nil? ? value.nil? : false)
+  Footnote = ::Struct.new :index, :id, :text
+
+  class AttributeEntry
+    attr_reader :name, :value, :negate
+
+    def initialize name, value, negate = nil
+      @name = name
+      @value = value
+      @negate = negate.nil? ? value.nil? : negate
     end
 
-    def save_to(block_attributes)
+    def save_to block_attributes
       (block_attributes[:attribute_entries] ||= []) << self
     end
+  end
+
+  # Public Parsed and stores a partitioned title (i.e., title & subtitle).
+  class Title
+    attr_reader :main
+    attr_reader :subtitle
+    attr_reader :combined
+
+    def initialize val, opts = {}
+      # TODO separate sanitization by type (:cdata for HTML/XML, :plain for non-SGML, false for none)
+      if (@sanitized = opts[:sanitize]) && val.include?('<')
+        val = val.gsub(XmlSanitizeRx, '').tr_s(' ', ' ').strip
+      end
+      if (@combined = val).include? ': '
+        @main, _, @subtitle = val.rpartition ': '
+      else
+        @main = val
+        @subtitle = nil
+      end
+    end
 
-    #def save_to_next_block(document)
-    #  (document.attributes[:pending_attribute_entries] ||= []) << self
-    #end
+    def sanitized?
+      @sanitized
+    end
+
+    def subtitle?
+      !!@subtitle
+    end
+
+    def to_s
+      @combined
+    end
   end
 
   # Public A read-only integer value indicating the level of security that
@@ -45,7 +78,7 @@ class Document < AbstractBlock
   # of the source file and disables any macro other than the include macro.
   #
   # A value of 10 (SERVER) disallows the document from setting attributes that
-  # would affect the rendering of the document, in addition to all the security
+  # would affect the conversion of the document, in addition to all the security
   # features of SafeMode::SAFE. For instance, this value disallows changing the
   # backend or the source-highlighter using an attribute defined in the source
   # document. This is the most fundamental level of security for server-side
@@ -68,6 +101,20 @@ class Document < AbstractBlock
   # this level is not currently implemented (and therefore not enforced)!
   attr_reader :safe
 
+  # Public: Get the Boolean AsciiDoc compatibility mode
+  #
+  # enabling this attribute activates the following syntax changes:
+  # 
+  #   * single quotes as constrained emphasis formatting marks
+  #   * single backticks parsed as inline literal, formatted as monospace
+  #   * single plus parsed as constrained, monospaced inline formatting
+  #   * double plus parsed as constrained, monospaced inline formatting
+  #
+  attr_reader :compat_mode
+
+  # Public: Get the Boolean flag that indicates whether source map information is tracked by the parser
+  attr_reader :sourcemap
+
   # Public: Get the Hash of document references
   attr_reader :references
 
@@ -77,263 +124,342 @@ class Document < AbstractBlock
   # Public: Get the Hash of callouts
   attr_reader :callouts
 
-  # Public: The section level 0 block
+  # Public: Get the level-0 Section
   attr_reader :header
 
-  # Public: Base directory for rendering this document. Defaults to directory of the source file.
+  # Public: Get the String base directory for converting this document.
+  #
+  # Defaults to directory of the source file.
   # If the source is a string, defaults to the current directory.
   attr_reader :base_dir
 
-  # Public: A reference to the parent document of this nested document.
+  # Public: Get a reference to the parent Document of this nested document.
   attr_reader :parent_document
 
-  # Public: The extensions registry
+  # Public: Get the Reader associated with this document
+  attr_reader :reader
+
+  # Public: Get the Converter associated with this document
+  attr_reader :converter
+
+  # Public: Get the extensions registry
   attr_reader :extensions
 
-  # Public: Initialize an Asciidoc object.
+  # Public: Initialize a {Document} object.
   #
-  # data    - The Array of Strings holding the Asciidoc source document. (default: [])
-  # options - A Hash of options to control processing, such as setting the safe mode (:safe),
-  #           suppressing the header/footer (:header_footer) and attribute overrides (:attributes)
-  #           (default: {})
+  # data    - The AsciiDoc source data as a String or String Array. (default: nil)
+  # options - A Hash of options to control processing (e.g., safe mode value (:safe), backend (:backend),
+  #           header/footer toggle (:header_footer), custom attributes (:attributes)). (default: {})
   #
   # Examples
   #
-  #   data = File.readlines(filename)
-  #   doc  = Asciidoctor::Document.new(data)
-  #   puts doc.render
-  def initialize(data = [], options = {})
-    super(self, :document)
-
-    if options[:parent]
-      @parent_document = options.delete(:parent)
-      options[:base_dir] ||= @parent_document.base_dir
+  #   data = File.read filename
+  #   doc = Asciidoctor::Document.new data
+  #   puts doc.convert
+  def initialize data = nil, options = {}
+    super self, :document
+
+    if (parent_doc = options.delete :parent)
+      @parent_document = parent_doc
+      options[:base_dir] ||= parent_doc.base_dir
+      @references = parent_doc.references.inject({}) do |accum, (key,ref)|
+        if key == :footnotes
+          accum[:footnotes] = []
+        else
+          accum[key] = ref
+        end
+        accum
+      end
       # QUESTION should we support setting attribute in parent document from nested document?
       # NOTE we must dup or else all the assignments to the overrides clobbers the real attributes
-      @attribute_overrides = @parent_document.attributes.dup
-      @safe = @parent_document.safe
-      @renderer = @parent_document.renderer
+      attr_overrides = parent_doc.attributes.dup
+      attr_overrides.delete 'doctype'
+      attr_overrides.delete 'compat-mode'
+      @attribute_overrides = attr_overrides
+      @safe = parent_doc.safe
+      @compat_mode = parent_doc.compat_mode
+      @sourcemap = parent_doc.sourcemap
+      @converter = parent_doc.converter
       initialize_extensions = false
-      @extensions = @parent_document.extensions
+      @extensions = parent_doc.extensions
     else
       @parent_document = nil
+      @references = {
+        :ids => {},
+        :footnotes => [],
+        :links => [],
+        :images => [],
+        :indexterms => [],
+        :includes => ::Set.new,
+      }
       # copy attributes map and normalize keys
       # attribute overrides are attributes that can only be set from the commandline
       # a direct assignment effectively makes the attribute a constant
       # a nil value or name with leading or trailing ! will result in the attribute being unassigned
-      @attribute_overrides = (options[:attributes] || {}).inject({}) do |collector,(key,value)|
-        if key.start_with?('!')
+      attr_overrides = {}
+      (options[:attributes] || {}).each do |key, value|
+        if key.start_with? '!'
           key = key[1..-1]
           value = nil
-        elsif key.end_with?('!')
-          key = key[0..-2]
+        elsif key.end_with? '!'
+          key = key.chop
           value = nil
         end
-        collector[key.downcase] = value
-        collector
+        attr_overrides[key.downcase] = value
       end
-      @safe = nil
-      @renderer = nil
-      initialize_extensions = Asciidoctor.const_defined?('Extensions')
-      @extensions = nil # initialize furthur down
-    end
-
-    @header = nil
-    @references = {
-      :ids => {},
-      :footnotes => [],
-      :links => [],
-      :images => [],
-      :indexterms => [],
-      :includes => Set.new,
-    }
-    @counters = {}
-    @callouts = Callouts.new
-    @attributes_modified = Set.new
-    @options = options
-    unless @parent_document
+      @attribute_overrides = attr_overrides
       # safely resolve the safe mode from const, int or string
-      if @safe.nil? && !(safe_mode = @options[:safe])
+      if !(safe_mode = options[:safe])
         @safe = SafeMode::SECURE
-      elsif safe_mode.is_a?(Fixnum)
+      elsif ::Fixnum === safe_mode
         # be permissive in case API user wants to define new levels
         @safe = safe_mode
       else
+        # NOTE: not using infix rescue for performance reasons, see https://github.com/jruby/jruby/issues/1816
         begin
-          @safe = SafeMode.const_get(safe_mode.to_s.upcase).to_i
+          @safe = SafeMode.const_get(safe_mode.to_s.upcase)
         rescue
-          @safe = SafeMode::SECURE.to_i
+          @safe = SafeMode::SECURE
         end
       end
+      @sourcemap = options[:sourcemap]
+      @compat_mode = false
+      @converter = nil
+      initialize_extensions = defined? ::Asciidoctor::Extensions
+      @extensions = nil # initialize furthur down
     end
-    @options[:header_footer] = @options.fetch(:header_footer, false)
 
-    @attributes['encoding'] = 'UTF-8'
-    @attributes['sectids'] = ''
-    @attributes['notitle'] = '' unless @options[:header_footer]
-    @attributes['toc-placement'] = 'auto'
-    @attributes['stylesheet'] = ''
-    @attributes['copycss'] = '' if @options[:header_footer]
-    @attributes['prewrap'] = ''
-    @attributes['attribute-undefined'] = COMPLIANCE[:attribute_undefined]
-    @attributes['attribute-missing'] = COMPLIANCE[:attribute_missing]
+    @parsed = false
+    @header = nil
+    @counters = {}
+    @callouts = Callouts.new
+    @attributes_modified = ::Set.new
+    @options = options
+    header_footer = (options[:header_footer] ||= false)
+
+    attrs = @attributes
+    attrs['encoding'] = 'UTF-8'
+    attrs['sectids'] = ''
+    attrs['notitle'] = '' unless header_footer
+    attrs['toc-placement'] = 'auto'
+    attrs['stylesheet'] = ''
+    attrs['webfonts'] = ''
+    attrs['copycss'] = '' if header_footer
+    attrs['prewrap'] = ''
+    attrs['attribute-undefined'] = Compliance.attribute_undefined
+    attrs['attribute-missing'] = Compliance.attribute_missing
+    attrs['iconfont-remote'] = ''
 
     # language strings
     # TODO load these based on language settings
-    @attributes['caution-caption'] = 'Caution'
-    @attributes['important-caption'] = 'Important'
-    @attributes['note-caption'] = 'Note'
-    @attributes['tip-caption'] = 'Tip'
-    @attributes['warning-caption'] = 'Warning'
-    @attributes['appendix-caption'] = 'Appendix'
-    @attributes['example-caption'] = 'Example'
-    @attributes['figure-caption'] = 'Figure'
-    #@attributes['listing-caption'] = 'Listing'
-    @attributes['table-caption'] = 'Table'
-    @attributes['toc-title'] = 'Table of Contents'
-    @attributes['manname-title'] = 'NAME'
-    @attributes['untitled-label'] = 'Untitled'
-    @attributes['version-label'] = 'Version'
-    @attributes['last-update-label'] = 'Last updated'
-
-    @attribute_overrides['asciidoctor'] = ''
-    @attribute_overrides['asciidoctor-version'] = VERSION
-
-    safe_mode_name = SafeMode.constants.detect {|l| SafeMode.const_get(l) == @safe}.to_s.downcase
-    @attribute_overrides['safe-mode-name'] = safe_mode_name
-    @attribute_overrides["safe-mode-#{safe_mode_name}"] = ''
-    @attribute_overrides['safe-mode-level'] = @safe
+    attrs['caution-caption'] = 'Caution'
+    attrs['important-caption'] = 'Important'
+    attrs['note-caption'] = 'Note'
+    attrs['tip-caption'] = 'Tip'
+    attrs['warning-caption'] = 'Warning'
+    attrs['appendix-caption'] = 'Appendix'
+    attrs['example-caption'] = 'Example'
+    attrs['figure-caption'] = 'Figure'
+    #attrs['listing-caption'] = 'Listing'
+    attrs['table-caption'] = 'Table'
+    attrs['toc-title'] = 'Table of Contents'
+    attrs['manname-title'] = 'NAME'
+    attrs['untitled-label'] = 'Untitled'
+    attrs['version-label'] = 'Version'
+    attrs['last-update-label'] = 'Last updated'
+
+    attr_overrides['asciidoctor'] = ''
+    attr_overrides['asciidoctor-version'] = VERSION
+
+    safe_mode_name = SafeMode.constants.detect {|l| SafeMode.const_get(l) == @safe }.to_s.downcase
+    attr_overrides['safe-mode-name'] = safe_mode_name
+    attr_overrides["safe-mode-#{safe_mode_name}"] = ''
+    attr_overrides['safe-mode-level'] = @safe
 
     # sync the embedded attribute w/ the value of options...do not allow override
-    @attribute_overrides['embedded'] = @options[:header_footer] ? nil : ''
+    attr_overrides['embedded'] = header_footer ? nil : ''
 
     # the only way to set the max-include-depth attribute is via the document options
     # 64 is the AsciiDoc default
-    @attribute_overrides['max-include-depth'] ||= 64
+    attr_overrides['max-include-depth'] ||= 64
 
     # the only way to enable uri reads is via the document options, disabled by default
-    unless !@attribute_overrides['allow-uri-read'].nil?
-      @attribute_overrides['allow-uri-read'] = nil
+    unless !attr_overrides['allow-uri-read'].nil?
+      attr_overrides['allow-uri-read'] = nil
     end
 
+    attr_overrides['user-home'] = USER_HOME
+
+    # legacy support for numbered attribute
+    attr_overrides['sectnums'] = attr_overrides.delete 'numbered' if attr_overrides.key? 'numbered'
+
     # if the base_dir option is specified, it overrides docdir as the root for relative paths
     # otherwise, the base_dir is the directory of the source file (docdir) or the current
     # directory of the input is a string
-    if @options[:base_dir].nil?
-      if @attribute_overrides['docdir']
-        @base_dir = @attribute_overrides['docdir'] = File.expand_path(@attribute_overrides['docdir'])
+    if options[:base_dir]
+      @base_dir = attr_overrides['docdir'] = ::File.expand_path(options[:base_dir])
+    else
+      if attr_overrides['docdir']
+        @base_dir = attr_overrides['docdir'] = ::File.expand_path(attr_overrides['docdir'])
       else
         #warn 'asciidoctor: WARNING: setting base_dir is recommended when working with string documents' unless nested?
-        @base_dir = @attribute_overrides['docdir'] = File.expand_path(Dir.pwd)
+        @base_dir = attr_overrides['docdir'] = ::File.expand_path(::Dir.pwd)
       end
-    else
-      @base_dir = @attribute_overrides['docdir'] = File.expand_path(@options[:base_dir])
     end
 
-    # allow common attributes backend and doctype to be set using options hash
-    unless @options[:backend].nil?
-      @attribute_overrides['backend'] = @options[:backend].to_s
+    # allow common attributes backend and doctype to be set using options hash, coerce values to string
+    if (backend_val = options[:backend])
+      attr_overrides['backend'] = %(#{backend_val})
     end
 
-    unless @options[:doctype].nil?
-      @attribute_overrides['doctype'] = @options[:doctype].to_s
+    if (doctype_val = options[:doctype])
+      attr_overrides['doctype'] = %(#{doctype_val})
     end
 
     if @safe >= SafeMode::SERVER
       # restrict document from setting copycss, source-highlighter and backend
-      @attribute_overrides['copycss'] ||= nil
-      @attribute_overrides['source-highlighter'] ||= nil
-      @attribute_overrides['backend'] ||= DEFAULT_BACKEND
+      attr_overrides['copycss'] ||= nil
+      attr_overrides['source-highlighter'] ||= nil
+      attr_overrides['backend'] ||= DEFAULT_BACKEND
       # restrict document from seeing the docdir and trim docfile to relative path
-      if !@parent_document && @attribute_overrides.has_key?('docfile')
-        @attribute_overrides['docfile'] = @attribute_overrides['docfile'][(@attribute_overrides['docdir'].length + 1)..-1]
+      if !parent_doc && attr_overrides.key?('docfile')
+        attr_overrides['docfile'] = attr_overrides['docfile'][(attr_overrides['docdir'].length + 1)..-1]
       end
-      @attribute_overrides['docdir'] = ''
+      attr_overrides['docdir'] = ''
+      attr_overrides['user-home'] = '.'
       if @safe >= SafeMode::SECURE
         # assign linkcss (preventing css embedding) unless explicitly disabled from the commandline or API
         # effectively the same has "has key 'linkcss' and value == nil"
-        unless @attribute_overrides.fetch('linkcss', '').nil?
-          @attribute_overrides['linkcss'] = ''
+        unless attr_overrides.fetch('linkcss', '').nil?
+          attr_overrides['linkcss'] = ''
         end
         # restrict document from enabling icons
-        @attribute_overrides['icons'] ||= nil
+        attr_overrides['icons'] ||= nil
       end
     end
     
-    @attribute_overrides.delete_if {|key, val|
+    attr_overrides.delete_if do |key, val|
       verdict = false
       # a nil value undefines the attribute 
       if val.nil?
-        @attributes.delete(key)
-      # a negative key (trailing !) undefines the attribute
-      # NOTE already normalize above as key with nil value
-      #elsif key.end_with? '!'
-      #  @attributes.delete(key[0..-2])
-      # a negative key (leading !) undefines the attribute
-      # NOTE already normalize above as key with nil value
-      #elsif key.start_with? '!'
-      #  @attributes.delete(key[1..-1])
-      # otherwise it's an attribute assignment
+        attrs.delete(key)
       else
         # a value ending in @ indicates this attribute does not override
         # an attribute with the same key in the document souce
-        if val.is_a?(String) && val.end_with?('@')
+        if (val.is_a? ::String) && (val.end_with? '@')
           val = val.chop
           verdict = true
         end
-        @attributes[key] = val
+        attrs[key] = val
       end
       verdict
-    }
+    end
+
+    @compat_mode = true if attrs.key? 'compat-mode'
 
-    if !@parent_document
+    if parent_doc
+      # setup default doctype (backend is fixed)
+      attrs['doctype'] ||= DEFAULT_DOCTYPE
+
+      # don't need to do the extra processing within our own document
+      # FIXME line info isn't reported correctly within include files in nested document
+      @reader = Reader.new data, options[:cursor]
+
+      # Now parse the lines in the reader into blocks
+      # Eagerly parse (for now) since a subdocument is not a publicly accessible object
+      Parser.parse @reader, self
+
+      # should we call rewind in some sort of post-parse function?
+      @callouts.rewind
+      @parsed = true
+    else
       # setup default backend and doctype
-      @attributes['backend'] ||= DEFAULT_BACKEND
-      @attributes['doctype'] ||= DEFAULT_DOCTYPE
-      update_backend_attributes
+      attrs['backend'] ||= DEFAULT_BACKEND
+      attrs['doctype'] ||= DEFAULT_DOCTYPE
+      update_backend_attributes attrs['backend'], true
 
-      #@attributes['indir'] = @attributes['docdir']
-      #@attributes['infile'] = @attributes['docfile']
+      #attrs['indir'] = attrs['docdir']
+      #attrs['infile'] = attrs['docfile']
 
       # dynamic intrinstic attribute values
-      now = Time.new
-      @attributes['localdate'] ||= now.strftime('%Y-%m-%d')
-      @attributes['localtime'] ||= now.strftime('%H:%M:%S %Z')
-      @attributes['localdatetime'] ||= [@attributes['localdate'], @attributes['localtime']] * ' '
-      
+      now = ::Time.now
+      localdate = (attrs['localdate'] ||= now.strftime('%Y-%m-%d'))
+      unless (localtime = attrs['localtime'])
+        begin
+          localtime = attrs['localtime'] = now.strftime('%H:%M:%S %Z')
+        rescue
+          localtime = attrs['localtime'] = now.strftime('%H:%M:%S')
+        end
+      end
+      attrs['localdatetime'] ||= %(#{localdate} #{localtime})
+
       # docdate, doctime and docdatetime should default to
       # localdate, localtime and localdatetime if not otherwise set
-      @attributes['docdate'] ||= @attributes['localdate']
-      @attributes['doctime'] ||= @attributes['localtime']
-      @attributes['docdatetime'] ||= @attributes['localdatetime']
+      attrs['docdate'] ||= localdate
+      attrs['doctime'] ||= localtime
+      attrs['docdatetime'] ||= %(#{localdate} #{localtime})
 
       # fallback directories
-      @attributes['stylesdir'] ||= '.'
-      @attributes['iconsdir'] ||= File.join(@attributes.fetch('imagesdir', './images'), 'icons')
+      attrs['stylesdir'] ||= '.'
+      attrs['iconsdir'] ||= ::File.join(attrs.fetch('imagesdir', './images'), 'icons')
+
+      @extensions = if initialize_extensions
+        registry = if (ext_registry = options[:extensions_registry])
+          if (ext_registry.is_a? Extensions::Registry) ||
+              (::RUBY_ENGINE_JRUBY && (ext_registry.is_a? ::AsciidoctorJ::Extensions::ExtensionRegistry))
+            ext_registry
+          end
+        elsif (ext_block = options[:extensions]).is_a? ::Proc
+          Extensions.build_registry(&ext_block)
+        end
+        (registry ||= Extensions::Registry.new).activate self
+      end
 
-      @extensions = initialize_extensions ? Extensions::Registry.new(self) : nil
-      @reader = PreprocessorReader.new self, data, Asciidoctor::Reader::Cursor.new(@attributes['docfile'], @base_dir)
+      @reader = PreprocessorReader.new self, data, Reader::Cursor.new(attrs['docfile'], @base_dir)
+    end
+  end
 
-      if @extensions && @extensions.preprocessors?
-        @extensions.load_preprocessors(self).each do |processor|
-          @reader = processor.process(@reader, @reader.lines) || @reader
+  # Public: Parse the AsciiDoc source stored in the {Reader} into an abstract syntax tree.
+  #
+  # If the data parameter is not nil, create a new {PreprocessorReader} and assigned it to the reader
+  # property of this object. Otherwise, continue with the reader that was created in {#initialize}. 
+  # Pass the reader to {Parser.parse} to parse the source data into an abstract syntax tree.
+  #
+  # If parsing has already been performed, this method returns without performing any processing.
+  #
+  # data - The optional replacement AsciiDoc source data as a String or String Array. (default: nil)
+  #
+  # Returns this [Document]
+  def parse data = nil
+    if @parsed
+      self
+    else
+      doc = self
+      # create reader if data is provided (used when data is not known at the time the Document object is created)
+      @reader = PreprocessorReader.new doc, data, Reader::Cursor.new(@attributes['docfile'], @base_dir) if data
+
+      if (exts = @parent_document ? nil : @extensions) && exts.preprocessors?
+        exts.preprocessors.each do |ext|
+          @reader = ext.process_method[doc, @reader] || @reader
         end
       end
-    else
-      # don't need to do the extra processing within our own document
-      # FIXME line info isn't reported correctly within include files in nested document
-      @reader = Reader.new data, options[:cursor]
-    end
 
-    # Now parse the lines in the reader into blocks
-    Lexer.parse(@reader, self, :header_only => @options.fetch(:parse_header_only, false)) 
+      # Now parse the lines in the reader into blocks
+      Parser.parse @reader, doc, :header_only => !!@options[:parse_header_only]
 
-    @callouts.rewind
+      # should we call rewind in some sort of post-parse function?
+      @callouts.rewind
 
-    if !@parent_document && @extensions && @extensions.treeprocessors?
-      @extensions.load_treeprocessors(self).each do |processor|
-        processor.process
+      if exts && exts.treeprocessors?
+        exts.treeprocessors.each do |ext|
+          if (result = ext.process_method[doc]) && Document === result && result != doc
+            doc = result
+          end
+        end
       end
+
+      @parsed = true
+      doc
     end
   end
 
@@ -344,15 +470,15 @@ class Document < AbstractBlock
   #
   # returns the next number in the sequence for the specified counter
   def counter(name, seed = nil)
-    if !@counters.has_key? name
+    if (attr_is_seed = !(attr_val = @attributes[name]).nil_or_empty?) && @counters.key?(name)
+      @counters[name] = nextval(attr_val)
+    else
       if seed.nil?
-        seed = nextval(@attributes.has_key?(name) ? @attributes[name] : 0)
+        seed = nextval(attr_is_seed ? attr_val : 0)
       elsif seed.to_i.to_s == seed
         seed = seed.to_i
       end
       @counters[name] = seed
-    else
-      @counters[name] = nextval(@counters[name])
     end
 
     (@attributes[name] = @counters[name])
@@ -378,7 +504,7 @@ class Document < AbstractBlock
   #
   # returns the next value in the sequence according to the current value's type
   def nextval(current)
-    if current.is_a?(Integer)
+    if current.is_a?(::Integer)
       current + 1
     else
       intval = current.to_i
@@ -393,7 +519,7 @@ class Document < AbstractBlock
   def register(type, value)
     case type
     when :ids
-      if value.is_a?(Array)
+      if value.is_a?(::Array)
         @references[:ids][value[0]] = (value[1] || '[' + value[0] + ']')
       else
         @references[:ids][value] = '[' + value + ']'
@@ -408,7 +534,7 @@ class Document < AbstractBlock
   end
 
   def footnotes?
-    not @references[:footnotes].empty?
+    !@references[:footnotes].empty?
   end
 
   def footnotes
@@ -416,16 +542,16 @@ class Document < AbstractBlock
   end
 
   def nested?
-    @parent_document ? true : false
+    !!@parent_document
   end
 
   def embedded?
     # QUESTION should this be !@options[:header_footer] ?
-    @attributes.has_key? 'embedded'
+    @attributes.key? 'embedded'
   end
 
   def extensions?
-    @extensions ? true : false
+    !!@extensions
   end
 
   # Make the raw source for the Document available.
@@ -439,11 +565,11 @@ class Document < AbstractBlock
   end
 
   def doctype
-    @attributes['doctype']
+    @doctype ||= @attributes['doctype']
   end
 
   def backend
-    @attributes['backend']
+    @backend ||= @attributes['backend']
   end
 
   def basebackend? base
@@ -460,18 +586,38 @@ class Document < AbstractBlock
     @header.title = title
   end
 
-  # We need to be able to return some semblance of a title
-  def doctitle(opts = {})
-    if !(val = @attributes.fetch('title', '')).empty?
+  # Public: Resolves the primary title for the document
+  #
+  # Searches the locations to find the first non-empty
+  # value:
+  #
+  #  * document-level attribute named title
+  #  * header title (known as the document title)
+  #  * title of the first section
+  #  * document-level attribute named untitled-label (if :use_fallback option is set)
+  #
+  # If no value can be resolved, nil is returned.
+  #
+  # If the :partition attribute is specified, the value is parsed into an Document::Title object.
+  # If the :sanitize attribute is specified, XML elements are removed from the value.
+  #
+  # Returns the resolved title as a [Title] if the :partition option is passed or a [String] if not
+  # or nil if no value can be resolved.
+  def doctitle opts = {}
+    if !(val = @attributes['title'].nil_or_empty?)
       val = title
-    elsif !(sect = first_section).nil? && sect.title?
+    elsif (sect = first_section) && sect.title?
       val = sect.title
+    elsif opts[:use_fallback] && (val = @attributes['untitled-label'])
+      # use val set in condition
     else
-      return nil
+      return
     end
     
-    if opts[:sanitize] && val.include?('<')
-      val.gsub(/<[^>]+>/, '').tr_s(' ', ' ').strip
+    if opts[:partition]
+      Title.new val, opts
+    elsif opts[:sanitize] && val.include?('<')
+      val.gsub(XmlSanitizeRx, '').tr_s(' ', ' ').strip
     else
       val
     end
@@ -493,21 +639,26 @@ class Document < AbstractBlock
   end
 
   def notitle
-    !@attributes.has_key?('showtitle') && @attributes.has_key?('notitle')
+    !@attributes.key?('showtitle') && @attributes.key?('notitle')
   end
 
   def noheader
-    @attributes.has_key? 'noheader'
+    @attributes.key? 'noheader'
+  end
+
+  def nofooter
+    @attributes.key? 'nofooter'
   end
 
   # QUESTION move to AbstractBlock?
   def first_section
-    has_header? ? @header : (@blocks || []).detect{|e| e.is_a? Section}
+    has_header? ? @header : (@blocks || []).detect{|e| e.context == :section }
   end
 
   def has_header?
     @header ? true : false
   end
+  alias :header? :has_header?
 
   # Public: Append a content Block to this Document.
   #
@@ -538,58 +689,75 @@ class Document < AbstractBlock
   # Internal: Branch the attributes so that the original state can be restored
   # at a future time.
   def save_attributes
-    # enable toc and numbered by default in DocBook backend
+    # enable toc and sectnums (i.e., numbered) by default in DocBook backend
     # NOTE the attributes_modified should go away once we have a proper attribute storage & tracking facility
-    if @attributes['basebackend'] == 'docbook'
-      @attributes['toc'] = '' unless attribute_locked?('toc') || @attributes_modified.include?('toc')
-      @attributes['numbered'] = '' unless attribute_locked?('numbered') || @attributes_modified.include?('numbered')
+    if (attrs = @attributes)['basebackend'] == 'docbook'
+      attrs['toc'] = '' unless attribute_locked?('toc') || @attributes_modified.include?('toc')
+      attrs['sectnums'] = '' unless attribute_locked?('sectnums') || @attributes_modified.include?('sectnums')
     end
 
-    unless @attributes.has_key?('doctitle') || (val = doctitle).nil?
-      @attributes['doctitle'] = val
+    unless attrs.key?('doctitle') || !(val = doctitle)
+      attrs['doctitle'] = val
     end
 
     # css-signature cannot be updated after header attributes are processed
-    if !@id && @attributes.has_key?('css-signature')
-      @id = @attributes['css-signature']
-    end
+    @id = attrs['css-signature'] unless @id
 
-    toc_val = @attributes['toc']
-    toc2_val = @attributes['toc2']
-    toc_position_val = @attributes['toc-position']
+    toc_position_val = if (toc_val = (attrs.delete('toc2') ? 'left' : attrs['toc']))
+      # toc-placement allows us to separate position from using fitted slot vs macro
+      (toc_placement = attrs.fetch('toc-placement', 'macro')) && toc_placement != 'auto' ? toc_placement : attrs['toc-position']
+    else
+      nil
+    end
 
-    if (!toc_val.nil? && (toc_val != '' || toc_position_val.to_s != '')) || !toc2_val.nil?
+    if toc_val && (!toc_val.empty? || !toc_position_val.nil_or_empty?)
       default_toc_position = 'left'
+      # TODO rename toc2 to aside-toc
       default_toc_class = 'toc2'
-      position = [toc_position_val, toc2_val, toc_val].find {|pos| pos.to_s != ''}
-      position = default_toc_position if !position && !toc2_val.nil?
-      @attributes['toc'] = ''
+      if !toc_position_val.nil_or_empty?
+        position = toc_position_val
+      elsif !toc_val.empty?
+        position = toc_val
+      else
+        position = default_toc_position
+      end
+      attrs['toc'] = ''
+      attrs['toc-placement'] = 'auto'
       case position
       when 'left', '<', '&lt;'
-        @attributes['toc-position'] = 'left'
+        attrs['toc-position'] = 'left'
       when 'right', '>', '&gt;'
-        @attributes['toc-position'] = 'right'
+        attrs['toc-position'] = 'right'
       when 'top', '^'
-        @attributes['toc-position'] = 'top'
+        attrs['toc-position'] = 'top'
       when 'bottom', 'v'
-        @attributes['toc-position'] = 'bottom'
-      when 'center'
-        @attributes.delete('toc2')
+        attrs['toc-position'] = 'bottom'
+      when 'preamble', 'macro'
+        attrs['toc-position'] = 'content'
+        attrs['toc-placement'] = position
+        default_toc_class = nil
+      else
+        attrs.delete 'toc-position'
         default_toc_class = nil
-        default_toc_position = 'center'
       end
-      @attributes['toc-class'] ||= default_toc_class if default_toc_class
-      @attributes['toc-position'] ||= default_toc_position if default_toc_position
+      attrs['toc-class'] ||= default_toc_class if default_toc_class
     end
 
-    @original_attributes = @attributes.dup
+    if attrs.key? 'compat-mode'
+      attrs['source-language'] = attrs['language'] if attrs.has_key? 'language'
+      @compat_mode = true
+    else
+      @compat_mode = false
+    end
+
+    @original_attributes = attrs.dup
 
     # unfreeze "flexible" attributes
     unless nested?
       FLEXIBLE_ATTRIBUTES.each do |name|
         # turning a flexible attribute off should be permanent
         # (we may need more config if that's not always the case)
-        if @attribute_overrides.has_key?(name) && !@attribute_overrides[name].nil?
+        if @attribute_overrides.key?(name) && @attribute_overrides[name]
           @attribute_overrides.delete(name)
         end
       end
@@ -597,7 +765,10 @@ class Document < AbstractBlock
   end
 
   # Internal: Restore the attributes to the previously saved state
+  #--
+  # QUESTION should we restore attributes after parse?
   def restore_attributes
+    # QUESTION shouldn't this be a dup in case we convert again?
     @attributes = @original_attributes
   end
 
@@ -608,12 +779,15 @@ class Document < AbstractBlock
 
   # Internal: Replay attribute assignments at the block level
   def playback_attributes(block_attributes)
-    if block_attributes.has_key? :attribute_entries
+    if block_attributes.key? :attribute_entries
       block_attributes[:attribute_entries].each do |entry|
+        name = entry.name
         if entry.negate
-          @attributes.delete(entry.name)
+          @attributes.delete name
+          @compat_mode = false if name == 'compat-mode'
         else
-          @attributes[entry.name] = entry.value
+          @attributes[name] = entry.value
+          @compat_mode = true if name == 'compat-mode'
         end
       end
     end
@@ -634,11 +808,15 @@ class Document < AbstractBlock
     if attribute_locked?(name)
       false
     else
-      @attributes[name] = apply_attribute_value_subs(value)
-      @attributes_modified << name
-      if name == 'backend'
-        update_backend_attributes()
+      case name
+      when 'backend'
+        update_backend_attributes apply_attribute_value_subs(value)
+      when 'doctype'
+        update_doctype_attributes apply_attribute_value_subs(value)
+      else
+        @attributes[name] = apply_attribute_value_subs(value)
       end
+      @attributes_modified << name
       true
     end
   end
@@ -666,124 +844,226 @@ class Document < AbstractBlock
   #
   # Returns true if the attribute is locked, false otherwise
   def attribute_locked?(name)
-    @attribute_overrides.has_key?(name)
+    @attribute_overrides.key?(name)
   end
 
   # Internal: Apply substitutions to the attribute value
   #
-  # If the value is an inline passthrough macro (e.g., pass:[text]), then
-  # apply the substitutions defined on the macro to the text. Otherwise,
-  # apply the verbatim substitutions to the value.
+  # If the value is an inline passthrough macro (e.g., pass:<subs>[value]),
+  # apply the substitutions defined in <subs> to the value, or leave the value
+  # unmodified if no substitutions are specified.  If the value is not an
+  # inline passthrough macro, apply header substitutions to the value.
   #
   # value - The String attribute value on which to perform substitutions
   #
-  # Returns The String value with substitutions performed.
+  # Returns The String value with substitutions performed
   def apply_attribute_value_subs(value)
-    if value.match(REGEXP[:pass_macro_basic])
-      # copy match for Ruby 1.8.7 compat
-      m = $~
+    if (m = AttributeEntryPassMacroRx.match(value))
       if !m[1].empty?
         subs = resolve_pass_subs m[1]
-        subs.empty? ? m[2] : apply_subs(m[2], subs)
+        subs.empty? ? m[2] : (apply_subs m[2], subs)
       else
         m[2]
       end
     else
-      apply_header_subs(value)
+      apply_header_subs value
     end
   end
 
   # Public: Update the backend attributes to reflect a change in the selected backend
-  def update_backend_attributes()
-    backend = @attributes['backend']
-    if BACKEND_ALIASES.has_key? backend
-      backend = @attributes['backend'] = BACKEND_ALIASES[backend]
-    end
-    basebackend = backend.sub(REGEXP[:trailing_digit], '')
-    page_width = DEFAULT_PAGE_WIDTHS[basebackend]
-    if page_width
-      @attributes['pagewidth'] = page_width
-    else
-      @attributes.delete('pagewidth')
-    end
-    @attributes["backend-#{backend}"] = ''
-    @attributes['basebackend'] = basebackend
-    @attributes["basebackend-#{basebackend}"] = ''
-    # REVIEW cases for the next two assignments
-    @attributes["#{backend}-#{@attributes['doctype']}"] = ''
-    @attributes["#{basebackend}-#{@attributes['doctype']}"] = ''
-    ext = DEFAULT_EXTENSIONS[basebackend] || '.html'
-    @attributes['outfilesuffix'] = ext
-    file_type = ext[1..-1]
-    @attributes['filetype'] = file_type
-    @attributes["filetype-#{file_type}"] = ''
-  end
-
-  def renderer(opts = {})
-    return @renderer if @renderer
-    
-    render_options = {}
+  #
+  # This method also handles updating the related doctype attributes if the
+  # doctype attribute is assigned at the time this method is called.
+  def update_backend_attributes new_backend, force = false
+    if force || (new_backend && new_backend != @attributes['backend'])
+      attrs = @attributes
+      current_backend = attrs['backend']
+      current_basebackend = attrs['basebackend']
+      current_doctype = attrs['doctype']
+      if new_backend.start_with? 'xhtml'
+        attrs['htmlsyntax'] = 'xml'
+        new_backend = new_backend[1..-1]
+      elsif new_backend.start_with? 'html'
+        attrs['htmlsyntax'] = 'html'
+      end
+      if (resolved_name = BACKEND_ALIASES[new_backend])
+        new_backend = resolved_name
+      end
+      if current_backend
+        attrs.delete %(backend-#{current_backend})
+        if current_doctype
+          attrs.delete %(backend-#{current_backend}-doctype-#{current_doctype})
+        end
+      end
+      if current_doctype
+        attrs[%(doctype-#{current_doctype})] = ''
+        attrs[%(backend-#{new_backend}-doctype-#{current_doctype})] = ''
+      end
+      attrs['backend'] = new_backend
+      attrs[%(backend-#{new_backend})] = ''
+      # (re)initialize converter
+      if (@converter = create_converter).is_a? Converter::BackendInfo
+        new_basebackend = @converter.basebackend
+        attrs['outfilesuffix'] = @converter.outfilesuffix unless attribute_locked? 'outfilesuffix'
+        new_filetype = @converter.filetype
+      else
+        new_basebackend = new_backend.sub TrailingDigitsRx, ''
+        # QUESTION should we be forcing the basebackend to html if unknown?
+        new_outfilesuffix = DEFAULT_EXTENSIONS[new_basebackend] || '.html'
+        new_filetype = new_outfilesuffix[1..-1]
+        attrs['outfilesuffix'] = new_outfilesuffix unless attribute_locked? 'outfilesuffix'
+      end
+      if (current_filetype = attrs['filetype'])
+        attrs.delete %(filetype-#{current_filetype})
+      end
+      attrs['filetype'] = new_filetype
+      attrs[%(filetype-#{new_filetype})] = ''
+      if (page_width = DEFAULT_PAGE_WIDTHS[new_basebackend])
+        attrs['pagewidth'] = page_width
+      else
+        attrs.delete 'pagewidth'
+      end
+      if new_basebackend != current_basebackend
+        if current_basebackend
+          attrs.delete %(basebackend-#{current_basebackend})
+          if current_doctype
+            attrs.delete %(basebackend-#{current_basebackend}-doctype-#{current_doctype})
+          end
+        end
+        attrs['basebackend'] = new_basebackend
+        attrs[%(basebackend-#{new_basebackend})] = ''
+        attrs[%(basebackend-#{new_basebackend}-doctype-#{current_doctype})] = '' if current_doctype
+      end
+      # clear cached backend value
+      @backend = nil
+    end
+  end
 
-    # Load up relevant Document @options
-    if @options.has_key? :template_dir
-      render_options[:template_dirs] = [@options[:template_dir]]
-    elsif @options.has_key? :template_dirs
-      render_options[:template_dirs] = @options[:template_dirs]
+  def update_doctype_attributes new_doctype
+    if new_doctype && new_doctype != @attributes['doctype']
+      attrs = @attributes
+      current_doctype = attrs['doctype']
+      current_backend = attrs['backend']
+      current_basebackend = attrs['basebackend']
+      if current_doctype
+        attrs.delete %(doctype-#{current_doctype})
+        attrs.delete %(backend-#{current_backend}-doctype-#{current_doctype}) if current_backend
+        attrs.delete %(basebackend-#{current_basebackend}-doctype-#{current_doctype}) if current_basebackend
+      end
+      attrs['doctype'] = new_doctype
+      attrs[%(doctype-#{new_doctype})] = ''
+      attrs[%(backend-#{current_backend}-doctype-#{new_doctype})] = '' if current_backend
+      attrs[%(basebackend-#{current_basebackend}-doctype-#{new_doctype})] = '' if current_basebackend
+      # clear cached doctype value
+      @doctype = nil
     end
-    
-    render_options[:template_cache] = @options.fetch(:template_cache, true)
-    render_options[:backend] = @attributes.fetch('backend', 'html5')
-    render_options[:template_engine] = @options[:template_engine]
-    render_options[:eruby] = @options.fetch(:eruby, 'erb')
-    render_options[:compact] = @options.fetch(:compact, false)
-    
-    # Override Document @option settings with options passed in
-    render_options.merge! opts
+  end
 
-    @renderer = Renderer.new(render_options)
+  # TODO document me
+  def create_converter
+    converter_opts = {}
+    converter_opts[:htmlsyntax] = @attributes['htmlsyntax']
+    template_dirs = if (template_dir = @options[:template_dir])
+      converter_opts[:template_dirs] = [template_dir]
+    elsif (template_dirs = @options[:template_dirs])
+      converter_opts[:template_dirs] = template_dirs
+    end
+    if template_dirs
+      converter_opts[:template_cache] = @options.fetch :template_cache, true
+      converter_opts[:template_engine] = @options[:template_engine]
+      converter_opts[:template_engine_options] = @options[:template_engine_options]
+      converter_opts[:eruby] = @options[:eruby]
+    end
+    converter_factory = if (converter = @options[:converter])
+      Converter::Factory.new ::Hash[backend, converter]
+    else
+      Converter::Factory.default false
+    end
+    # QUESTION should we honor the convert_opts?
+    # QUESTION should we pass through all options and attributes too?
+    #converter_opts.update opts
+    converter_factory.create backend, converter_opts
   end
 
-  # Public: Render the Asciidoc document using the templates
-  # loaded by Renderer. If a :template_dir is not specified,
-  # or a template is missing, the renderer will fall back to
+  # Public: Convert the AsciiDoc document using the templates
+  # loaded by the Converter. If a :template_dir is not specified,
+  # or a template is missing, the converter will fall back to
   # using the appropriate built-in template.
-  def render(opts = {})
+  def convert opts = {}
+    parse unless @parsed
     restore_attributes
-    r = renderer(opts)
 
-    # QUESTION should we add Preserializeprocessors? is it the right name?
-    #if !@parent_document && @extensions && @extensions.preserializeprocessors?
-    #  @extensions.load_preserializeprocessors(self).each do |processor|
-    #    processor.process r
-    #  end
-    #end
+    # QUESTION should we add processors that execute before conversion begins?
+    unless @converter
+      fail %(asciidoctor: FAILED: missing converter for backend '#{backend}'. Processing aborted.)
+    end
 
     if doctype == 'inline'
       # QUESTION should we warn if @blocks.size > 0 and the first block is not a paragraph?
-      if !(block = @blocks.first).nil? && block.content_model != :compound
+      if (block = @blocks[0]) && block.content_model != :compound
         output = block.content
       else
         output = ''
       end
     else
-      output = @options.merge(opts)[:header_footer] ? r.render('document', self).strip : r.render('embedded', self)
+      transform = ((opts.key? :header_footer) ? opts[:header_footer] : @options[:header_footer]) ? 'document' : 'embedded'
+      output = @converter.convert self, transform
     end
 
-    if !@parent_document && @extensions
-      if @extensions.postprocessors?
-        @extensions.load_postprocessors(self).each do |processor|
-          output = processor.process output
+    unless @parent_document
+      if (exts = @extensions) && exts.postprocessors?
+        exts.postprocessors.each do |ext|
+          output = ext.process_method[self, output]
         end
       end
-      @extensions.reset
     end
 
     output
   end
 
+  # Alias render to convert to maintain backwards compatibility
+  alias :render :convert
+
+  # Public: Write the output to the specified file
+  #
+  # If the converter responds to :write, delegate the work of writing the file
+  # to that method. Otherwise, write the output the specified file.
+  def write output, target
+    if @converter.is_a? Writer
+      @converter.write output, target
+    else
+      if target.respond_to? :write
+        target.write output.chomp
+        # ensure there's a trailing endline
+        target.write EOL
+      else
+        ::File.open(target, 'w') {|f| f.write output }
+      end
+      nil
+    end
+  end
+
+=begin
+  def convert_to target, opts = {}
+    start = ::Time.now.to_f if (monitor = opts[:monitor])
+    output = (r = converter opts).convert
+    monitor[:convert] = ::Time.now.to_f - start if monitor
+
+    unless target.respond_to? :write
+      @attributes['outfile'] = target = ::File.expand_path target
+      @attributes['outdir'] = ::File.dirname target
+    end
+
+    start = ::Time.now.to_f if monitor
+    r.write output, target
+    monitor[:write] = ::Time.now.to_f - start if monitor 
+
+    output
+  end
+=end
+
   def content
-    # per AsciiDoc-spec, remove the title before rendering the body,
-    # regardless of whether the header is rendered)
+    # NOTE per AsciiDoc-spec, remove the title before converting the body
     @attributes.delete('title')
     super
   end
@@ -814,22 +1094,28 @@ class Document < AbstractBlock
 
       content = nil
 
-      docinfo = @attributes.has_key?('docinfo')
-      docinfo1 = @attributes.has_key?('docinfo1')
-      docinfo2 = @attributes.has_key?('docinfo2')
+      docinfo = @attributes.key?('docinfo')
+      docinfo1 = @attributes.key?('docinfo1')
+      docinfo2 = @attributes.key?('docinfo2')
       docinfo_filename = "docinfo#{qualifier}#{ext}"
       if docinfo1 || docinfo2
         docinfo_path = normalize_system_path(docinfo_filename)
         content = read_asset(docinfo_path)
-        content = sub_attributes(content.lines.entries).join unless content.nil?
+        unless content.nil?
+          # FIXME normalize these lines!
+          content.force_encoding ::Encoding::UTF_8 if FORCE_ENCODING
+          content = sub_attributes(content.split EOL) * EOL
+        end
       end
 
-      if (docinfo || docinfo2) && @attributes.has_key?('docname')
+      if (docinfo || docinfo2) && @attributes.key?('docname')
         docinfo_path = normalize_system_path("#{@attributes['docname']}-#{docinfo_filename}")
         content2 = read_asset(docinfo_path)
         unless content2.nil?
-          content2 = sub_attributes(content2.lines.entries).join
-          content = content.nil? ? content2 : "#{content}\n#{content2}"
+          # FIXME normalize these lines!
+          content2.force_encoding ::Encoding::UTF_8 if FORCE_ENCODING
+          content2 = sub_attributes(content2.split EOL) * EOL
+          content = content.nil? ? content2 : "#{content}#{EOL}#{content2}"
         end
       end
 
@@ -839,7 +1125,7 @@ class Document < AbstractBlock
   end
 
   def to_s
-    %[#{super.to_s} - #{doctitle}]  
+    %(#<#{self.class}@#{object_id} {doctype: #{doctype.inspect}, doctitle: #{(@header != nil ? @header.title : nil).inspect}, blocks: #{@blocks.size}}>)
   end
 
 end