asciidoctor 1.5.6.2 → 1.5.7

data/lib/asciidoctor/converter/manpage.rb

@@ -18,7 +18,7 @@ module Asciidoctor
     LeadingPeriodRx = /^\./
     EscapedMacroRx = /^(?:#{ESC}\\c\n)?#{ESC}\.((?:URL|MTO) ".*?" ".*?" )( |[^\s]*)(.*?)(?: *#{ESC}\\c)?$/
     MockBoundaryRx = /<\/?BOUNDARY>/
-    EmDashCharRefRx = /&#8212(?:;&#8203;)?/
+    EmDashCharRefRx = /&#8212;(?:&#8203;)?/
     EllipsisCharRefRx = /&#8230;(?:&#8203;)?/
 
     # Converts HTML entity references back to their original form, escapes
@@ -57,6 +57,7 @@ module Asciidoctor
         gsub('&#8656;', '\(lA').  # leftwards double arrow
         gsub('&#8658;', '\(rA').  # rightwards double arrow
         gsub('&#8203;', '\:').    # zero width space
+        gsub('&amp;','&').        # literal ampersand (NOTE must take place after any other replacement that includes &)
         gsub('\'', '\(aq').       # apostrophe-quote
         gsub(MockBoundaryRx, ''). # mock boundary
         gsub(ESC_BS, '\\').       # unescape troff backslash (NOTE update if more escapes are added)
@@ -66,7 +67,7 @@ module Asciidoctor
     end
 
     def skip_with_warning node, name = nil
-      warn %(asciidoctor: WARNING: converter missing for #{name || node.node_name} node in manpage backend)
+      logger.warn %(converter missing for #{name || node.node_name} node in manpage backend)
       nil
     end
 
@@ -81,7 +82,7 @@ module Asciidoctor
       # NOTE the first line enables the table (tbl) preprocessor, necessary for non-Linux systems
       result = [%('\\" t
 .\\"     Title: #{mantitle}
-.\\"    Author: #{(node.attr? 'authors') ? (node.attr 'authors') : '[see the "AUTHORS" section]'}
+.\\"    Author: #{(node.attr? 'authors') ? (node.attr 'authors') : '[see the "AUTHOR(S)" section]'}
 .\\" Generator: Asciidoctor #{node.attr 'asciidoctor-version'})]
       result << %(.\\"      Date: #{docdate}) if docdate
       result << %(.\\"    Manual: #{(manual = node.attr 'manmanual') || '\ \&'}
@@ -105,22 +106,33 @@ module Asciidoctor
       # define URL macro for portability
       # see http://web.archive.org/web/20060102165607/http://people.debian.org/~branden/talks/wtfm/wtfm.pdf
       #
-      # Use: .URL "http://www.debian.org" "Debian" "."
+      # Usage
+      #
+      # .URL "http://www.debian.org" "Debian" "."
       #
       # * First argument: the URL
       # * Second argument: text to be hyperlinked
-      # * Third (optional) argument: text that needs to immediately trail
-      #   the hyperlink without intervening whitespace
+      # * Third (optional) argument: text that needs to immediately trail the hyperlink without intervening whitespace
       result << '.de URL
-\\\\$2 \(laURL: \\\\$1 \(ra\\\\$3
+\\fI\\\\$2\\fP <\\\\$1>\\\\$3
 ..
-.if \n[.g] .mso www.tmac'
-      result << %(.LINKSTYLE #{node.attr 'man-linkstyle', 'blue R < >'})
+.als MTO URL
+.if \n[.g] \{\
+.  mso www.tmac
+.  am URL
+.    ad l
+.  .
+.  am MTO
+.    ad l
+.  .'
+      result << %(.  LINKSTYLE #{node.attr 'man-linkstyle', 'blue R < >'})
+      result << '.\}'
 
       unless node.noheader
         if node.attr? 'manpurpose'
-          result << %(.SH "#{node.attr 'manname-title'}"
-#{manify mantitle} \\- #{manify node.attr 'manpurpose'})
+          mannames = node.attr 'mannames', [manname]
+          result << %(.SH "#{(node.attr 'manname-title').upcase}"
+#{mannames.map {|n| manify n } * ', '} \\- #{manify node.attr 'manpurpose'})
         end
       end
 
@@ -132,14 +144,19 @@ module Asciidoctor
         result.concat(node.footnotes.map {|fn| %(#{fn.index}. #{fn.text}) })
       end
 
-      # FIXME detect single author and use appropriate heading; itemize the authors if multiple
-      if node.attr? 'authors'
-        result << %(.SH "AUTHOR(S)"
+      # FIXME we really need an API that returns the authors as an array
+      if (num_authors = (node.attr 'authorcount') || 0) > 0
+        if num_authors == 1
+          result << %(.SH "AUTHOR"
 .sp
-\\fB#{node.attr 'authors'}\\fP
-.RS 4
-Author(s).
-.RE)
+#{node.attr 'author'})
+        else
+          result << '.SH "AUTHORS"'
+          (1.upto num_authors).each do |i|
+            result << %(.sp
+#{node.attr "author_#{i}"})
+          end
+        end
       end
 
       result * LF
@@ -176,16 +193,14 @@ Author(s).
 
     def admonition node
       result = []
-      result << %(.if n \\{\\
-.sp
-.\\}
+      result << %(.if n .sp
 .RS 4
 .it 1 an-trap
 .nr an-no-space-flag 1
 .nr an-break-flag 1
 .br
 .ps +1
-.B #{node.attr 'textlabel'}#{node.title? ? "\\fP: #{manify node.title}" : nil}
+.B #{node.attr 'textlabel'}#{node.title? ? "\\fP: #{manify node.title}" : ''}
 .ps -1
 .br
 #{resolve_content node}
@@ -216,10 +231,12 @@ r lw(\n(.lu*75u/100u).'
       result * LF
     end
 
-    # TODO implement title for dlist
     # TODO implement horizontal (if it makes sense)
     def dlist node
       result = []
+      result << %(.sp
+.B #{manify node.title}
+.br) if node.title?
       counter = 0
       node.items.each do |terms, dd|
         counter += 1
@@ -265,15 +282,11 @@ r lw(\n(.lu*75u/100u).'
 .B #{manify node.captioned_title}
 .br) if node.title?
       result << %(.sp
-.if n \\{\\
-.RS 4
-.\\}
+.if n .RS 4
 .nf
 #{manify node.content}
 .fi
-.if n \\{\\
-.RE
-.\\})
+.if n .RE)
       result * LF
     end
 
@@ -283,15 +296,11 @@ r lw(\n(.lu*75u/100u).'
 .B #{manify node.title}
 .br) if node.title?
       result << %(.sp
-.if n \\{\\
-.RS 4
-.\\}
+.if n .RS 4
 .nf
 #{manify node.content}
 .fi
-.if n \\{\\
-.RE
-.\\})
+.if n .RE)
       result * LF
     end
 
@@ -308,8 +317,8 @@ r lw(\n(.lu*75u/100u).'
 \\h'-04' #{idx + 1}.\\h'+01'\\c
 .\\}
 .el \\{\\
-.sp -1
-.IP " #{idx + 1}." 4.2
+.  sp -1
+.  IP " #{idx + 1}." 4.2
 .\\}
 #{manify item.text})
         result << item.content if item.blocks?
@@ -378,7 +387,7 @@ r lw(\n(.lu*75u/100u).'
     def stem node
       title_element = node.title? ? %(.sp
 .B #{manify node.title}
-.br) : nil
+.br) : ''
       open, close = BLOCK_MATH_DELIMITERS[node.style.to_sym]
 
       unless ((equation = node.content).start_with? open) && (equation.end_with? close)
@@ -538,8 +547,8 @@ allbox tab(:);'
 \\h'-04'\\(bu\\h'+03'\\c
 .\\}
 .el \\{\\
-.sp -1
-.IP \\(bu 2.3
+.  sp -1
+.  IP \\(bu 2.3
 .\\}
 #{manify item.text}]
         result << item.content if item.blocks?
@@ -574,8 +583,8 @@ allbox tab(:);'
     end
 
     def video node
-      start_param = (node.attr? 'start', nil, false) ? %(&start=#{node.attr 'start'}) : nil
-      end_param = (node.attr? 'end', nil, false) ? %(&end=#{node.attr 'end'}) : nil
+      start_param = (node.attr? 'start', nil, false) ? %(&start=#{node.attr 'start'}) : ''
+      end_param = (node.attr? 'end', nil, false) ? %(&end=#{node.attr 'end'}) : ''
       result = []
       result << %(.sp
 .B #{manify node.title}
@@ -588,17 +597,18 @@ allbox tab(:);'
       target = node.target
       case node.type
       when :link
-        if (text = node.text) == target
-          text = nil
-        else
-          text = text.gsub '"', %[#{ESC_BS}(dq]
-        end
         if target.start_with? 'mailto:'
           macro = 'MTO'
-          target = target[7..-1].sub '@', %[#{ESC_BS}(at]
+          target = target.slice 7, target.length
         else
           macro = 'URL'
         end
+        if (text = node.text) == target
+          text = ''
+        else
+          text = text.gsub '"', %[#{ESC_BS}(dq]
+        end
+        target = target.sub '@', %[#{ESC_BS}(at] if macro == 'MTO'
         %(#{ESC_BS}c#{LF}#{ESC_FS}#{macro} "#{target}" "#{text}" )
       when :xref
         refid = (node.attr 'refid') || target
@@ -607,7 +617,8 @@ allbox tab(:);'
         # These are anchor points, which shouldn't be visible
         ''
       else
-        warn %(asciidoctor: WARNING: unknown anchor type: #{node.type.inspect})
+        logger.warn %(unknown anchor type: #{node.type.inspect})
+        nil
       end
     end
 
@@ -669,7 +680,7 @@ allbox tab(:);'
       when :strong
         %(#{ESC_BS}fB<BOUNDARY>#{node.text}</BOUNDARY>#{ESC_BS}fP)
       when :monospaced
-        %(#{ESC_BS}f[CR]<BOUNDARY>#{node.text}</BOUNDARY>#{ESC_BS}fP)
+        %[#{ESC_BS}f(CR<BOUNDARY>#{node.text}</BOUNDARY>#{ESC_BS}fP]
       when :single
         %[#{ESC_BS}(oq<BOUNDARY>#{node.text}</BOUNDARY>#{ESC_BS}(cq]
       when :double
@@ -682,5 +693,16 @@ allbox tab(:);'
     def resolve_content node
       node.content_model == :compound ? node.content : %(.sp#{LF}#{manify node.content})
     end
+
+    def write_alternate_pages mannames, manvolnum, target
+      if mannames && mannames.size > 1
+        mannames.shift
+        manvolext = %(.#{manvolnum})
+        dir, basename = ::File.split target
+        mannames.each do |manname|
+          ::IO.write ::File.join(dir, %(#{manname}#{manvolext})), %(.so #{basename})
+        end
+      end
+    end
   end
 end

data/lib/asciidoctor/converter/template.rb

@@ -39,8 +39,6 @@ module Asciidoctor
       @caches = { :scans => ::ThreadSafe::Cache.new, :templates => ::ThreadSafe::Cache.new }
     rescue ::LoadError
       @caches = { :scans => {}, :templates => {} }
-      # FIXME perhaps only warn if the cache option is enabled (meaning not disabled)?
-      warn 'asciidoctor: WARNING: gem \'thread_safe\' is not installed. This gem is recommended when using custom backend templates.'
     end
 
     def self.caches
@@ -77,6 +75,7 @@ module Asciidoctor
       end
       case opts[:template_cache]
       when true
+        logger.warn 'gem \'thread_safe\' is not installed. This gem is recommended when using the built-in template cache.' unless defined? ::ThreadSafe
         @caches = self.class.caches
       when ::Hash
         @caches = opts[:template_cache]
@@ -105,24 +104,25 @@ module Asciidoctor
       engine = @engine
       @template_dirs.each do |template_dir|
         # FIXME need to think about safe mode restrictions here
-        next unless ::File.directory?(template_dir = (path_resolver.system_path template_dir, nil))
+        next unless ::File.directory?(template_dir = (path_resolver.system_path template_dir))
 
-        # 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))
+          if ::File.directory?(engine_dir = %(#{template_dir}/#{engine}))
             template_dir = engine_dir
           end
+        else
+          # NOTE last matching template wins for template name if no engine is given
+          file_pattern = '*'
         end
 
-        # example: templates/html5 or templates/haml/html5
-        if ::File.directory?(backend_dir = (::File.join template_dir, backend))
+        # example: templates/html5 (engine not set) or templates/haml/html5 (engine set)
+        if ::File.directory?(backend_dir = %(#{template_dir}/#{backend}))
           template_dir = backend_dir
         end
 
-        pattern = ::File.join template_dir, file_pattern
+        pattern = %(#{template_dir}/#{file_pattern})
 
         if (scan_cache = @caches[:scans])
           template_cache = @caches[:templates]
@@ -161,7 +161,7 @@ module Asciidoctor
         end
       else
         metaclass.send :define_method, name do |node|
-          (template.render node).chomp
+          (template.render node).rstrip
         end
       end
     end
@@ -193,7 +193,7 @@ module Asciidoctor
       if template_name == 'document'
         (template.render node, opts).strip
       else
-        (template.render node, opts).chomp
+        (template.render node, opts).rstrip
       end
     end
 
@@ -280,7 +280,7 @@ module Asciidoctor
         end
         result[name] = template
       end
-      if helpers || ::File.file?(helpers = (::File.join template_dir, 'helpers.rb'))
+      if helpers || ::File.file?(helpers = %(#{template_dir}/helpers.rb))
         require helpers
       end
       result

data/lib/asciidoctor/core_ext.rb

@@ -2,8 +2,12 @@ require 'asciidoctor/core_ext/nil_or_empty'
 require 'asciidoctor/core_ext/regexp/is_match'
 if RUBY_MIN_VERSION_1_9
   require 'asciidoctor/core_ext/string/limit_bytesize'
-  require 'asciidoctor/core_ext/1.8.7/io/write' if RUBY_ENGINE == 'opal'
+  if RUBY_ENGINE == 'opal'
+    require 'asciidoctor/core_ext/1.8.7/io/binread'
+    require 'asciidoctor/core_ext/1.8.7/io/write'
+  end
 elsif RUBY_ENGINE != 'opal'
+  require 'asciidoctor/core_ext/1.8.7/base64/strict_encode64'
   require 'asciidoctor/core_ext/1.8.7/hash/key'
   require 'asciidoctor/core_ext/1.8.7/io/binread'
   require 'asciidoctor/core_ext/1.8.7/io/write'

data/lib/asciidoctor/core_ext/1.8.7/base64/strict_encode64.rb

@@ -0,0 +1,6 @@
+# Educate Ruby 1.8.7 about the Base64#strict_encode64 method.
+module Base64
+  def strict_encode64 bin
+    (self.encode64 bin).delete %(\n)
+  end
+end

data/lib/asciidoctor/document.rb

@@ -1,22 +1,85 @@
 # encoding: UTF-8
 module Asciidoctor
-# Public: Methods for parsing and converting AsciiDoc documents.
+# Public: The Document class represents a parsed AsciiDoc document.
 #
-# There are several strategies for getting the title of the document:
+# Document is the root node of a parsed AsciiDoc document. It provides an
+# abstract syntax tree (AST) that represents the structure of the AsciiDoc
+# document from which the Document object was parsed.
 #
-# doctitle - value of title attribute, if assigned and non-empty,
-#            otherwise title of first section in document, if present
-#            otherwise nil
-# name - an alias of doctitle
-# title - value of the title attribute, or nil if not present
-# first_section.title - title of first section in document, if present
-# header.title - title of section level 0
+# Although the constructor can be used to create an empty document object, more
+# commonly, you'll load the document object from AsciiDoc source using the
+# primary API methods, {Asciidoctor.load} or {Asciidoctor.load_file}. When
+# using one of these APIs, you almost always want to set the safe mode to
+# :safe (or :unsafe) to enable all of Asciidoctor's features.
 #
-# Keep in mind that you'll want to honor these document settings:
+#   Asciidoctor.load '= Hello, AsciiDoc!', safe: :safe
+#   # => Asciidoctor::Document { doctype: "article", doctitle: "Hello, Asciidoc!", blocks: 0 }
 #
-# 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
+# Instances of this class can be used to extract information from the document
+# or alter its structure. As such, the Document object is most often used in
+# extensions and by integrations.
+#
+# The most basic usage of the Document object is to retrieve the document's
+# title.
+#
+#   source = '= Document Title'
+#   document = Asciidoctor.load source, safe: :safe
+#   document.doctitle
+#   # => 'Document Title'
+#
+# If the document has no title, the {Document#doctitle} method returns the
+# title of the first section. If that check falls through, you can have the
+# method return a fallback value (the value of the untitled-label attribute).
+#
+#   Asciidoctor.load('no doctitle', safe: :safe).doctitle use_fallback: true
+#   # => "Untitled"
+#
+# You can also use the Document object to access document attributes defined in
+# the header, such as the author and doctype.
+#
+#   source = '= Document Title
+#   Author Name
+#   :doctype: book'
+#   document = Asciidoctor.load source, safe: :safe
+#   document.author
+#   # => 'Author Name'
+#   document.doctype
+#   # => 'book'
+#
+# You can retrieve arbitrary document attributes defined in the header using
+# {Document#attr} or check for the existence of one using {Document#attr?}:
+#
+#   source = '= Asciidoctor
+#   :uri-project: https://asciidoctor.org'
+#   document = Asciidoctor.load source, safe: :safe
+#   document.attr 'uri-project'
+#   # => 'https://asciidoctor.org'
+#   document.attr? 'icons'
+#   # => false
+#
+# Starting at the Document object, you can begin walking the document tree using
+# the {Document#blocks} method:
+#
+#   source = 'paragraph contents
+#
+#   [sidebar]
+#   sidebar contents'
+#   doc = Asciidoctor.load source, safe: :safe
+#   doc.blocks.map {|block| block.context }
+#   # => [:paragraph, :sidebar]
+#
+# You can discover block nodes at any depth in the tree using the
+# {AbstractBlock#find_by} method.
+#
+#   source = '****
+#   paragraph in sidebar
+#   ****'
+#   doc = Asciidoctor.load source, safe: :safe
+#   doc.find_by(context: :paragraph).map {|block| block.context }
+#   # => [:paragraph]
+#
+# Loading a document object is the first step in the conversion process. You
+# can take the process to completion by calling the {Document#convert} method.
 class Document < AbstractBlock
 
   Footnote = ::Struct.new :index, :id, :text
@@ -134,9 +197,6 @@ class Document < AbstractBlock
   # Public: Get the Hash of document counters
   attr_reader :counters
 
-  # Public: Get the Hash of callouts
-  attr_reader :callouts
-
   # Public: Get the level-0 Section
   attr_reader :header
 
@@ -158,6 +218,9 @@ class Document < AbstractBlock
   # Public: Get the Reader associated with this document
   attr_reader :reader
 
+  # Public: Get/Set the PathResolver instance used to resolve paths in this Document.
+  attr_reader :path_resolver
+
   # Public: Get the Converter associated with this document
   attr_reader :converter
 
@@ -183,11 +246,11 @@ class Document < AbstractBlock
     if (parent_doc = options.delete :parent)
       @parent_document = parent_doc
       options[:base_dir] ||= parent_doc.base_dir
+      options[:catalog_assets] = true if parent_doc.options[:catalog_assets]
       @catalog = parent_doc.catalog.inject({}) do |accum, (key, table)|
         accum[key] = (key == :footnotes ? [] : table)
         accum
       end
-      @callouts = parent_doc.callouts
       # 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 = attr_overrides = parent_doc.attributes.dup
@@ -199,6 +262,8 @@ class Document < AbstractBlock
       @safe = parent_doc.safe
       @attributes['compat-mode'] = '' if (@compat_mode = parent_doc.compat_mode)
       @sourcemap = parent_doc.sourcemap
+      @timings = nil
+      @path_resolver = parent_doc.path_resolver
       @converter = parent_doc.converter
       initialize_extensions = false
       @extensions = parent_doc.extensions
@@ -211,25 +276,33 @@ class Document < AbstractBlock
         :links => [],
         :images => [],
         :indexterms => [],
-        :includes => ::Set.new,
+        :callouts => Callouts.new,
+        :includes => {},
       }
-      @callouts = Callouts.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
-      attr_overrides = {}
-      (options[:attributes] || {}).each do |key, value|
-        if key.start_with? '!'
-          key = key[1..-1]
-          value = nil
+      @attribute_overrides = attr_overrides = {}
+      (options[:attributes] || {}).each do |key, val|
+        if key.end_with? '@'
+          if key.start_with? '!'
+            key, val = (key.slice 1, key.length), false
+          elsif key.end_with? '!@'
+            key, val = (key.slice 0, key.length - 2), false
+          else
+            key, val = key.chop, %(#{val}@)
+          end
+        elsif key.start_with? '!'
+          key, val = (key.slice 1, key.length), val == '@' ? false : nil
         elsif key.end_with? '!'
-          key = key.chop
-          value = nil
+          key, val = key.chop, val == '@' ? false : nil
         end
-        attr_overrides[key.downcase] = value
+        attr_overrides[key.downcase] = val
+      end
+      if (to_file = options[:to_file])
+        attr_overrides['outfilesuffix'] = ::File.extname to_file
       end
-      @attribute_overrides = attr_overrides
       # safely resolve the safe mode from const, int or string
       if !(safe_mode = options[:safe])
         @safe = SafeMode::SECURE
@@ -246,6 +319,8 @@ class Document < AbstractBlock
       end
       @compat_mode = attr_overrides.key? 'compat-mode'
       @sourcemap = options[:sourcemap]
+      @timings = options.delete :timings
+      @path_resolver = PathResolver.new
       @converter = nil
       initialize_extensions = defined? ::Asciidoctor::Extensions
       @extensions = nil # initialize furthur down
@@ -292,9 +367,8 @@ class Document < AbstractBlock
     attrs['table-caption'] = 'Table'
     attrs['toc-title'] = 'Table of Contents'
     #attrs['preface-title'] = 'Preface'
-    attrs['manname-title'] = 'NAME'
     attrs['section-refsig'] = 'Section'
-    #attrs['part-refsig'] = 'Part'
+    attrs['part-refsig'] = 'Part'
     attrs['chapter-refsig'] = 'Chapter'
     attrs['appendix-caption'] = attrs['appendix-refsig'] = 'Appendix'
     attrs['untitled-label'] = 'Untitled'
@@ -327,7 +401,7 @@ class Document < AbstractBlock
     elsif attr_overrides['docdir']
       @base_dir = attr_overrides['docdir']
     else
-      #warn 'asciidoctor: WARNING: setting base_dir is recommended when working with string documents' unless nested?
+      #logger.warn 'setting base_dir is recommended when working with string documents' unless nested?
       @base_dir = attr_overrides['docdir'] = ::Dir.pwd
     end
 
@@ -354,10 +428,8 @@ class Document < AbstractBlock
       if @safe >= SafeMode::SECURE
         attr_overrides['max-attribute-value-size'] = 4096 unless attr_overrides.key? 'max-attribute-value-size'
         # assign linkcss (preventing css embedding) unless explicitly disabled from the commandline or API
-        # effectively the same has "has key 'linkcss' and value == nil"
-        unless attr_overrides.fetch('linkcss', '').nil?
-          attr_overrides['linkcss'] = ''
-        end
+        #attr_overrides['linkcss'] = (attr_overrides.fetch 'linkcss', '') || nil
+        attr_overrides['linkcss'] = '' unless attr_overrides.key? 'linkcss'
         # restrict document from enabling icons
         attr_overrides['icons'] ||= nil
       end
@@ -367,18 +439,16 @@ class Document < AbstractBlock
     @max_attribute_value_size = (size = (attr_overrides['max-attribute-value-size'] ||= nil)) ? size.to_i.abs : nil
 
     attr_overrides.delete_if do |key, val|
-      verdict = false
-      # a nil value undefines the attribute
-      if val.nil?
-        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
+        # a value ending in @ allows document to override value
         if ::String === val && (val.end_with? '@')
-          val = val.chop
-          verdict = true
+          val, verdict = val.chop, true
         end
         attrs[key] = val
+      else
+        # a nil or false value both unset the attribute; only a nil value locks it
+        attrs.delete key
+        verdict = val == false
       end
       verdict
     end
@@ -393,6 +463,7 @@ class Document < AbstractBlock
       # 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]
+      @source_location = @reader.cursor if @sourcemap
 
       # Now parse the lines in the reader into blocks
       # Eagerly parse (for now) since a subdocument is not a publicly accessible object
@@ -441,24 +512,24 @@ class Document < AbstractBlock
 
       # fallback directories
       attrs['stylesdir'] ||= '.'
-      attrs['iconsdir'] ||= ::File.join(attrs.fetch('imagesdir', './images'), 'icons')
+      attrs['iconsdir'] ||= %(#{attrs.fetch 'imagesdir', './images'}/icons)
 
       if initialize_extensions
         if (ext_registry = options[:extension_registry])
-          # QUESTION should we warn the value type of the option is not a registry or boolean?
-          unless Extensions::Registry === ext_registry || (::RUBY_ENGINE_JRUBY &&
+          # QUESTION should we warn if the value type of this option is not a registry
+          if Extensions::Registry === ext_registry || (::RUBY_ENGINE_JRUBY &&
               ::AsciidoctorJ::Extensions::ExtensionRegistry === ext_registry)
-            ext_registry = Extensions::Registry.new
+            @extensions = ext_registry.activate self
           end
         elsif ::Proc === (ext_block = options[:extensions])
-          ext_registry = Extensions.create(&ext_block)
-        else
-          ext_registry = Extensions::Registry.new
+          @extensions = Extensions.create(&ext_block).activate self
+        elsif !Extensions.groups.empty?
+          @extensions = Extensions::Registry.new.activate self
         end
-        @extensions = ext_registry.activate self
       end
 
       @reader = PreprocessorReader.new self, data, (Reader::Cursor.new attrs['docfile'], @base_dir), :normalize => true
+      @source_location = @reader.cursor if @sourcemap
     end
   end
 
@@ -481,6 +552,7 @@ class Document < AbstractBlock
       # create reader if data is provided (used when data is not known at the time the Document object is created)
       if data
         @reader = PreprocessorReader.new doc, data, (Reader::Cursor.new @attributes['docfile'], @base_dir), :normalize => true
+        @source_location = @reader.cursor if @sourcemap
       end
 
       if (exts = @parent_document ? nil : @extensions) && exts.preprocessors?
@@ -583,6 +655,10 @@ class Document < AbstractBlock
     @catalog[:footnotes]
   end
 
+  def callouts
+    @catalog[:callouts]
+  end
+
   def nested?
     @parent_document ? true : false
   end
@@ -609,14 +685,24 @@ class Document < AbstractBlock
     @attributes['basebackend'] == base
   end
 
-  # The title explicitly defined in the document attributes
+  # Public: Return the doctitle as a String
+  #
+  # Returns the resolved doctitle as a [String] or nil if a doctitle cannot be resolved
   def title
-    @attributes['title']
+    doctitle
   end
 
+  # Public: Set the title on the document header
+  #
+  # Set the title of the document header to the specified value. If the header
+  # does not exist, it is first created.
+  #
+  # title - the String title to assign as the title of the document header
+  #
+  # Returns the new [String] title assigned to the document header
   def title= title
     unless (sect = @header)
-      (sect = (@header = Section.new self, 0, false)).sectname = 'header'
+      (sect = (@header = Section.new self, 0)).sectname = 'header'
     end
     sect.title = title
   end
@@ -641,14 +727,12 @@ class Document < AbstractBlock
   # 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)
-      val = sect.title
-    elsif opts[:use_fallback] && (val = @attributes['untitled-label'])
-      # use val set in condition
-    else
-      return
+    unless (val = @attributes['title'])
+      if (sect = first_section)
+        val = sect.title
+      elsif !(opts[:use_fallback] && (val = @attributes['untitled-label']))
+        return
+      end
     end
 
     if (separator = opts[:partition])
@@ -704,7 +788,7 @@ class Document < AbstractBlock
   #
   # Returns The parent Block
   def << block
-    enumerate_section block if block.context == :section
+    assign_numeral block if block.context == :section
     super
   end
 
@@ -800,9 +884,8 @@ class Document < AbstractBlock
 
   # Internal: Restore the attributes to the previously saved state (attributes in header)
   def restore_attributes
-    @callouts.rewind unless @parent_document
-    # QUESTION shouldn't this be a dup in case we convert again?
-    @attributes = @header_attributes
+    @catalog[:callouts].rewind unless @parent_document
+    @attributes.replace @header_attributes
   end
 
   # Internal: Delete any attributes stored for playback
@@ -914,7 +997,7 @@ class Document < AbstractBlock
       current_backend, current_basebackend, current_doctype = @backend, (attrs = @attributes)['basebackend'], @doctype
       if new_backend.start_with? 'xhtml'
         attrs['htmlsyntax'] = 'xml'
-        new_backend = new_backend[1..-1]
+        new_backend = new_backend.slice 1, new_backend.length
       elsif new_backend.start_with? 'html'
         attrs['htmlsyntax'] = 'html' unless attrs['htmlsyntax'] == 'xml'
       end
@@ -941,7 +1024,7 @@ class Document < AbstractBlock
       elsif @converter
         new_basebackend = new_backend.sub TrailingDigitsRx, ''
         if (new_outfilesuffix = DEFAULT_EXTENSIONS[new_basebackend])
-          new_filetype = new_outfilesuffix[1..-1]
+          new_filetype = new_outfilesuffix.slice 1, new_outfilesuffix.length
         else
           new_outfilesuffix, new_basebackend, new_filetype = '.html', 'html', 'html'
         end
@@ -1006,12 +1089,13 @@ class Document < AbstractBlock
   def create_converter
     converter_opts = {}
     converter_opts[:htmlsyntax] = @attributes['htmlsyntax']
-    template_dirs = if (template_dir = @options[:template_dir])
-      converter_opts[:template_dirs] = [template_dir]
+    if (template_dir = @options[:template_dir])
+      template_dirs = [template_dir]
     elsif (template_dirs = @options[:template_dirs])
-      converter_opts[:template_dirs] = template_dirs
+      template_dirs = Array template_dirs
     end
     if template_dirs
+      converter_opts[:template_dirs] = 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]
@@ -1033,9 +1117,8 @@ class Document < AbstractBlock
   # 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.
-  #--
-  # QUESTION should we dup @header_attributes before converting?
   def convert opts = {}
+    @timings.start :convert if @timings
     parse unless @parsed
     unless @safe >= SafeMode::SERVER || opts.empty?
       # QUESTION should we store these on the Document object?
@@ -1046,9 +1129,9 @@ class Document < AbstractBlock
     # QUESTION should we add extensions that execute before conversion begins?
 
     if doctype == 'inline'
-      if (block = @blocks[0])
+      if (block = @blocks[0] || @header)
         if block.content_model == :compound || block.content_model == :empty
-          warn %(asciidoctor: WARNING: no inline candidate; use the inline doctype to convert a single paragragh, verbatim, or raw block)
+          logger.warn 'no inline candidate; use the inline doctype to convert a single paragragh, verbatim, or raw block'
         else
           output = block.content
         end
@@ -1066,6 +1149,7 @@ class Document < AbstractBlock
       end
     end
 
+    @timings.record :convert if @timings
     output
   end
 
@@ -1076,7 +1160,10 @@ class Document < AbstractBlock
   #
   # If the converter responds to :write, delegate the work of writing the file
   # to that method. Otherwise, write the output the specified file.
+  #
+  # Returns nothing
   def write output, target
+    @timings.start :write if @timings
     if Writer === @converter
       @converter.write output, target
     else
@@ -1089,8 +1176,12 @@ class Document < AbstractBlock
       else
         ::IO.write target, output
       end
-      nil
+      if @backend == 'manpage' && ::String === target && (@converter.respond_to? :write_alternate_pages)
+        @converter.write_alternate_pages @attributes['mannames'], @attributes['manvolnum'], target
+      end
     end
+    @timings.record :write if @timings
+    nil
   end
 
 =begin