asciidoctor 0.1.1 → 0.1.2

data/asciidoctor.gemspec

@@ -6,39 +6,41 @@
 ## http://docs.rubygems.org/read/chapter/20
 Gem::Specification.new do |s|
   s.specification_version = 2 if s.respond_to? :specification_version=
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.rubygems_version = '1.3.5'
+  s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
+  s.rubygems_version = '1.8.5'
 
-  ## Leave these as is they will be modified for you by the rake gemspec task.
-  ## If your rubyforge_project name is different, then edit it and comment out
-  ## the sub! line in the Rakefile
+  ## This group of properties is updated automatically by the Rake build when
+  ## cutting a new release (see the validate task)
   s.name              = 'asciidoctor'
-  s.version           = '0.1.1'
-  s.date              = '2013-02-26'
+  s.version           = '0.1.2'
+  s.date              = '2013-04-25'
   s.rubyforge_project = 'asciidoctor'
 
   ## Make sure your summary is short. The description may be as long
   ## as you like.
-  s.summary     = "Pure Ruby Asciidoc to HTML rendering."
-  s.description = "A pure Ruby processor to turn Asciidoc-formatted documents into HTML (and, eventually, other formats perhaps)."
+  s.summary     = 'A native Ruby AsciiDoc syntax processor and publishing toolchain'
+  s.description = <<-EOS
+An open source text processor and publishing toolchain, written entirely in Ruby, for converting AsciiDoc markup into HTML 5, DocBook 4.5 and other formats. 
+EOS
+  s.license     = 'MIT'
 
   ## List the primary authors. If there are a bunch of authors, it's probably
   ## better to set the email to an email list or something. If you don't have
   ## a custom homepage, consider using your GitHub URL or the like.
-  s.authors  = ["Ryan Waldron", "Dan Allen", "Jeremy McAnally"]
-  s.email    = 'rew@erebor.com'
-  s.homepage = 'http://github.com/asciidoctor'
+  s.authors  = ['Ryan Waldron', 'Dan Allen', 'Jeremy McAnally', 'Jason Porter']
+  s.email    = ['rew@erebor.com', 'dan.j.allen@gmail.com']
+  s.homepage = 'http://asciidoctor.org'
 
   ## This gets added to the $LOAD_PATH so that 'lib/NAME.rb' can be required as
   ## require 'NAME.rb' or'/lib/NAME/file.rb' can be as require 'NAME/file.rb'
   s.require_paths = %w[lib]
 
   ## If your gem includes any executables, list them here.
-  s.executables = ["asciidoctor"]
+  s.executables = ['asciidoctor', 'asciidoctor-safe']
 
   ## Specify any RDoc options here. You'll want to add your README and
   ## LICENSE files to the extra_rdoc_files list.
-  s.rdoc_options = ["--charset=UTF-8"]
+  s.rdoc_options = ['--charset=UTF-8']
   s.extra_rdoc_files = %w[LICENSE]
 
   ## List your runtime dependencies here. Runtime dependencies are those
@@ -63,11 +65,12 @@ Gem::Specification.new do |s|
   s.files = %w[
     Gemfile
     LICENSE
-    README.asciidoc
+    README.adoc
     Rakefile
     asciidoctor.gemspec
     bin/asciidoctor
     bin/asciidoctor-safe
+    compat/asciidoc.conf
     lib/asciidoctor.rb
     lib/asciidoctor/abstract_block.rb
     lib/asciidoctor/abstract_node.rb
@@ -81,11 +84,11 @@ Gem::Specification.new do |s|
     lib/asciidoctor/cli/options.rb
     lib/asciidoctor/debug.rb
     lib/asciidoctor/document.rb
-    lib/asciidoctor/errors.rb
     lib/asciidoctor/helpers.rb
     lib/asciidoctor/inline.rb
     lib/asciidoctor/lexer.rb
     lib/asciidoctor/list_item.rb
+    lib/asciidoctor/path_resolver.rb
     lib/asciidoctor/reader.rb
     lib/asciidoctor/renderer.rb
     lib/asciidoctor/section.rb
@@ -94,17 +97,24 @@ Gem::Specification.new do |s|
     lib/asciidoctor/version.rb
     man/asciidoctor.1
     man/asciidoctor.ad
+    stylesheets/asciidoctor.css
     test/attributes_test.rb
     test/blocks_test.rb
     test/document_test.rb
     test/fixtures/asciidoc.txt
     test/fixtures/asciidoc_index.txt
     test/fixtures/ascshort.txt
+    test/fixtures/basic-docinfo.html
+    test/fixtures/basic-docinfo.xml
+    test/fixtures/basic.asciidoc
+    test/fixtures/docinfo.html
+    test/fixtures/docinfo.xml
     test/fixtures/dot.gif
     test/fixtures/encoding.asciidoc
     test/fixtures/include-file.asciidoc
     test/fixtures/list_elements.asciidoc
     test/fixtures/sample.asciidoc
+    test/fixtures/stylesheets/custom.css
     test/fixtures/tip.gif
     test/invoker_test.rb
     test/lexer_test.rb
@@ -112,6 +122,7 @@ Gem::Specification.new do |s|
     test/lists_test.rb
     test/options_test.rb
     test/paragraphs_test.rb
+    test/paths_test.rb
     test/preamble_test.rb
     test/reader_test.rb
     test/renderer_test.rb

data/compat/asciidoc.conf

@@ -0,0 +1,139 @@
+# This file is an AsciiDoc configuration file that makes
+# AsciiDoc conform with Asciidoctor's fixes and customizations.
+#
+# Place this file in the same directory as your AsciiDoc document and the
+# AsciiDoc processor (asciidoc) will automatically use it.
+
+[miscellaneous]
+newline=\n
+
+[attributes]
+# make html5 the default html backend
+backend-alias-html=html5
+linkcss=
+apostrophe='
+asterisk=*
+caret=^
+backtick=`
+# plus introduced in AsciiDoc 8.6.9
+plus=+
+space=" "
+tilde=~
+
+# enables fenced code blocks
+# I haven't sorted out yet how to do syntax highlighting
+[blockdef-fenced-code]
+delimiter=^```\w*$
+template::[blockdef-listing]
+
+# enables literal block to be used as code block
+[blockdef-literal]
+template::[source-filter-style]
+
+ifdef::basebackend-html[]
+
+[literal-inlinemacro]
+<code>{passtext}</code>
+
+[tags]
+monospaced=<code{1? class="{1}"}>|</code>
+
+[monospacedwords]
+<code>{words}</code>
+
+[tabletags-monospaced]
+paragraph=<p class="tableblock"><code>|</code></p>
+
+# support for document title in embedded documents
+ifeval::[not config.header_footer]
+[preamble]
+<h1>{title={doctitle}}</h1>{set:title-rendered:}
+<div id="preamble">
+<div class="sectionbody">
+|
+</div>
+</div>
+
+[sect1]
+{title-rendered%}<h1>{doctitle}</h1>
+<div class="sect1{style? {style}}{role? {role}}">
+<h2{id? id="{id}"}>{numbered?{sectnum} }{title}</h2>
+<div class="sectionbody">
+|
+</div>
+</div>
+endif::[]
+
+# override to add the admonition name to the class attribute of the outer element
+[admonitionblock]
+<div class="admonitionblock {name}{role? {role}}{unbreakable-option? unbreakable}"{id? id="{id}"}>
+<table><tr>
+<td class="icon">
+{data-uri%}{icons#}<img src="{icon={iconsdir}/{name}.png}" alt="{caption}">
+{data-uri#}{icons#}<img alt="{caption}" src="data:image/png;base64,
+{data-uri#}{icons#}{sys:"{python}" -u -c "import base64,sys; base64.encode(sys.stdin,sys.stdout)" < "{eval:os.path.join(r"{indir={outdir}}",r"{icon={iconsdir}/{name}.png}")}"}">
+{icons%}<div class="title">{caption}</div>
+</td>
+<td class="content">
+<div class="title">{title}</div>
+|
+</td>
+</tr></table>
+</div>
+
+# a common template for emitting the attribute for a quote or verse block
+# don't output attribution div if attribution or citetitle are both empty
+[attribution]
+{attribution,citetitle#}<div class="attribution">
+<cite>{citetitle}</cite>{attribution?<br>}
+&#8212; {attribution}
+{attribution,citetitle#}</div>
+
+# override to use blockquote element for content and cite element for cite title
+[quoteblock]
+<div class="quoteblock{role? {role}}{unbreakable-option? unbreakable}"{id? id="{id}"}>
+<div class="title">{title}</div>
+<blockquote>
+|
+</blockquote>
+template::[attribution]
+</div>
+
+# override to use cite element for cite title
+[verseblock]
+<div class="verseblock{role? {role}}{unbreakable-option? unbreakable}"{id? id="{id}"}>
+<div class="title">{title}</div>
+<pre class="content">
+|
+</pre>
+template::[attribution]
+</div>
+
+endif::basebackend-html[]
+
+# Override docinfo to support subtitle
+ifdef::basebackend-docbook[]
+
+[docinfo]
+ifndef::notitle[]
+{set2:subtitle_offset:{eval:'{doctitle}'.rfind(': ')}}
+{eval:{subtitle_offset} != -1}    <title>{eval:'{doctitle}'[0:{subtitle_offset}]}</title>
+{eval:{subtitle_offset} != -1}    <subtitle>{eval:'{doctitle}'[{subtitle_offset} + 2:]}</subtitle>
+{eval:{subtitle_offset} < 0}    <title>{doctitle}</title>
+endif::notitle[]
+    <date>{revdate}</date>
+# To ensure valid articleinfo/bookinfo when there is no AsciiDoc header.
+    {doctitle%}{revdate%}<date>{docdate}</date>
+    {authored#}<author>
+        <firstname>{firstname}</firstname>
+        <othername>{middlename}</othername>
+        <surname>{lastname}</surname>
+        <email>{email}</email>
+    {authored#}</author>
+    <authorinitials>{authorinitials}</authorinitials>
+<revhistory><revision>{revnumber?<revnumber>{revnumber}</revnumber>}<date>{revdate}</date>{authorinitials?<authorinitials>{authorinitials}</authorinitials>}{revremark?<revremark>{revremark}</revremark>}</revision></revhistory>
+{docinfo1,docinfo2#}{include:{docdir}/docinfo.xml}
+{docinfo,docinfo2#}{include:{docdir}/{docname}-docinfo.xml}
+<orgname>{orgname}</orgname>
+
+endif::basebackend-docbook[]

data/lib/asciidoctor.rb

@@ -1,5 +1,6 @@
-require 'rubygems'
+require 'rubygems' unless RUBY_VERSION >= '1.9'
 require 'strscan'
+require 'set'
 
 $:.unshift(File.dirname(__FILE__))
 #$:.unshift(File.join(File.dirname(__FILE__), '..', 'vendor'))
@@ -87,6 +88,9 @@ module Asciidoctor
 
   end
 
+  # The root path of the Asciidoctor gem
+  ROOT_PATH = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
   # The default document type
   # Can influence markup generated by render templates
   DEFAULT_DOCTYPE = 'article'
@@ -94,6 +98,12 @@ module Asciidoctor
   # The backend determines the format of the rendered output, default to html5
   DEFAULT_BACKEND = 'html5'
 
+  DEFAULT_STYLESHEET_PATH = File.join(ROOT_PATH, 'stylesheets', 'asciidoctor.css')
+
+  DEFAULT_STYLESHEET_KEYS = ['', 'DEFAULT'].to_set
+
+  DEFAULT_STYLESHEET_NAME = File.basename(DEFAULT_STYLESHEET_PATH)
+
   # Pointers to the preferred version for a given backend.
   BACKEND_ALIASES = {
     'html' => 'html5',
@@ -113,19 +123,35 @@ module Asciidoctor
     'markdown' => '.md'
   }
 
+  SECTION_LEVELS = {
+    '=' => 0,
+    '-' => 1,
+    '~' => 2,
+    '^' => 3,
+    '+' => 4
+  }
+
+  ADMONITION_STYLES = ['NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION'].to_set
+
+  # NOTE: AsciiDoc doesn't support pass style for paragraph
+  PARAGRAPH_STYLES = ['comment', 'example', 'literal', 'listing', 'normal', 'pass', 'quote', 'sidebar', 'source', 'verse'].to_set
+
+  VERBATIM_STYLES = ['literal', 'listing', 'source', 'verse'].to_set
+
   DELIMITED_BLOCKS = {
-    '--'   => :open,
-    '----' => :listing,
-    '....' => :literal,
-    '====' => :example,
-    '****' => :sidebar,
-    '____' => :quote,
-    '++++' => :pass,
-    '|===' => :table,
-    '!===' => :table,
-    '////' => :comment,
-    '```'  => :fenced_code,
-    '~~~'  => :fenced_code
+    # NOTE: AsciiDoc doesn't support pass style for open block
+    '--'   => [:open, ['comment', 'example', 'literal', 'listing', 'pass', 'quote', 'sidebar', 'source', 'verse', 'admonition'].to_set],
+    '----' => [:listing, ['literal', 'source'].to_set],
+    '....' => [:literal, ['listing', 'source'].to_set],
+    '====' => [:example, ['admonition'].to_set],
+    '****' => [:sidebar, Set.new],
+    '____' => [:quote, ['verse'].to_set],
+    '++++' => [:pass, Set.new],
+    '|===' => [:table, Set.new],
+    '!===' => [:table, Set.new],
+    '////' => [:comment, Set.new],
+    '```'  => [:fenced_code, Set.new],
+    '~~~'  => [:fenced_code, Set.new]
   }
 
   BREAK_LINES = {
@@ -156,6 +182,27 @@ module Asciidoctor
 
   LINE_FEED_ENTITY = '
' # or 

 
+  # Flags to control compliance with the behavior of AsciiDoc
+  COMPLIANCE = {
+    # AsciiDoc terminates paragraphs adjacent to
+    # block content (delimiter or block attribute list)
+    # Compliance value: true
+    # TODO what about literal paragraph?
+    :block_terminates_paragraph => true,
+
+    # AsciiDoc does not treat paragraphs labeled with a
+    # verbatim style (literal, listing, source, verse)
+    # as verbatim; override this behavior
+    # Compliance value: false
+    :strict_verbatim_paragraphs => true,
+
+    # AsciiDoc allows start and end delimiters around
+    # a block to be different lengths
+    # this option requires that they be the same
+    # Compliance value: false
+    :congruent_block_delimiters => true
+  }
+
   # The following pattern, which appears frequently, captures the contents between square brackets,
   # ignoring escaped closing brackets (closing brackets prefixed with a backslash '\' character)
   #
@@ -164,8 +211,11 @@ module Asciidoctor
   # Matches:
   # [enclosed text here] or [enclosed [text\] here]
   REGEXP = {
+    # NOTE: this is a inline admonition note
+    :admonition_inline => /^(#{ADMONITION_STYLES.to_a * '|'}):\s/,
+
     # [[Foo]]
-    :anchor           => /^\[\[([^\[\]]+)\]\]$/,
+    :anchor           => /^\[\[([^\s\[\]]+)\]\]$/,
 
     # Foowhatevs [[Bar]]
     :anchor_embedded  => /^(.*?)\s*\[\[([^\[\]]+)\]\]$/,
@@ -178,6 +228,14 @@ module Asciidoctor
     # NOTE position the most common blocks towards the front of the pattern
     :any_blk          => %r{^(?:--|(?:-|\.|=|\*|_|\+|/){4,}|[\|!]={3,}|(?:`|~){3,}.*)$},
 
+    # detect a list item of any sort
+    # [[:graph:]] is a non-blank character
+    :any_list         => /^(?:
+                             <?\d+>[[:blank:]]+[[:graph:]]|
+                             [[:blank:]]*(?:(?:-|\*|\.){1,5}|\d+\.|[A-Za-z]\.|[IVXivx]+\))[[:blank:]]+[[:graph:]]|
+                             [[:blank:]]*.*?(?::{2,4}|;;)(?:[[:blank:]]+[[:graph:]]|$)
+                           )/x,
+
     # :foo: bar
     # :Author: Dan
     # :numbered!:
@@ -204,10 +262,10 @@ module Asciidoctor
     # [NOTE, caption="Good to know"]
     # Can be defined by an attribute
     # [{lead}]
-    :blk_attr_list    => /^\[([\w\{].*)\]$/,
+    :blk_attr_list    => /^\[(|[[:blank:]]*[\w\{,"'].*)\]$/,
 
     # block attribute list or block id (bulk query)
-    :attr_line        => /^\[([\w\{].*|\[[^\[\]]+\])\]$/,
+    :attr_line        => /^\[(|[[:blank:]]*[\w\{,"'].*|\[[^\[\]]*\])\]$/,
 
     # attribute reference
     # {foo}
@@ -216,7 +274,7 @@ module Asciidoctor
 
     # The author info line the appears immediately following the document title
     # John Doe <john@anonymous.com>
-    :author_info      => /^\s*(\w[\w\-'.]*)(?: +(\w[\w\-'.]*))?(?: +(\w[\w\-'.]*))?(?: +<([^>]+)>)?$/,
+    :author_info      => /^(\w[\w\-'.]*)(?: +(\w[\w\-'.]*))?(?: +(\w[\w\-'.]*))?(?: +<([^>]+)>)?$/,
 
     # [[[Foo]]] (anywhere inline)
     :biblio_macro     => /\\?\[\[\[([\w:][\w:.-]*?)\]\]\]/,
@@ -229,7 +287,7 @@ module Asciidoctor
     :callout_scan     => /\\?<(\d+)>/,
 
     # <1> Foo
-    :colist           => /^<?(\d+)> (.*)/,
+    :colist           => /^<?(\d+)>[[:blank:]]+(.*)/,
 
     # ////
     # comment block
@@ -242,7 +300,15 @@ module Asciidoctor
     # one,two
     # one, two
     # one , two
-    :csv_delimiter    => /[[:space:]]*,[[:space:]]*/,
+    :csv_delimiter    => /[[:blank:]]*,[[:blank:]]*/,
+
+    # one;two
+    # one; two
+    # one ; two
+    :semicolon_delim  => /[[:blank:]]*;[[:blank:]]*/,
+
+    # one,two;three;four
+    :scsv_csv_delim   => /[[:blank:]]*[,;][[:blank:]]*/,
 
     # 29
     :digits           => /^\d+$/,
@@ -255,13 +321,14 @@ module Asciidoctor
     #   That which precedes 'bar' (see also, <<bar>>)
     # The term may be an attribute reference
     # {term_foo}:: {def_foo}
-    :dlist            => /^\s*(.*?)(:{2,4}|;;)(?:[[:blank:]]+(.*))?$/,
+    # REVIEW leading space has already been stripped, so may not need in regex
+    :dlist            => /^[[:blank:]]*(.*?)(:{2,4}|;;)(?:[[:blank:]]+(.*))?$/,
     :dlist_siblings   => {
                            # (?:.*?[^:])? - a non-capturing group which grabs longest sequence of characters that doesn't end w/ colon
-                           '::' => /^\s*((?:.*[^:])?)(::)(?:[[:blank:]]+(.*))?$/,
-                           ':::' => /^\s*((?:.*[^:])?)(:::)(?:[[:blank:]]+(.*))?$/,
-                           '::::' => /^\s*((?:.*[^:])?)(::::)(?:[[:blank:]]+(.*))?$/,
-                           ';;' => /^\s*(.*)(;;)(?:[[:blank:]]+(.*))?$/
+                           '::' => /^[[:blank:]]*((?:.*[^:])?)(::)(?:[[:blank:]]+(.*))?$/,
+                           ':::' => /^[[:blank:]]*((?:.*[^:])?)(:::)(?:[[:blank:]]+(.*))?$/,
+                           '::::' => /^[[:blank:]]*((?:.*[^:])?)(::::)(?:[[:blank:]]+(.*))?$/,
+                           ';;' => /^[[:blank:]]*(.*)(;;)(?:[[:blank:]]+(.*))?$/
                          },
     # ====
     #:example          => /^={4,}$/,
@@ -269,13 +336,15 @@ module Asciidoctor
     # footnote:[text]
     # footnoteref:[id,text]
     # footnoteref:[id]
-    :footnote_macro   => /\\?(footnote|footnoteref):\[((?:\\\]|[^\]])*?)\]/m,
+    :footnote_macro   => /\\?(footnote|footnoteref):\[((?:\\\]|[^\]])*?)\]/,
 
     # image::filename.png[Caption]
-    :image_blk        => /^image::(\S+?)\[(.*?)\]$/,
+    # video::http://youtube.com/12345[Cats vs Dogs]
+    :media_blk_macro  => /^(image|video|audio)::(\S+?)\[((?:\\\]|[^\]])*?)\]$/,
 
     # image:filename.png[Alt Text]
-    :image_macro      => /\\?image:([^\[]+)(?:\[([^\]]*)\])/,
+    # image:filename.png[More [Alt\] Text] (alt text becomes "More [Alt] Text")
+    :image_macro      => /\\?image:([^:\[]+)\[((?:\\\]|[^\]])*?)\]/,
 
     # indexterm:[Tigers,Big cats]
     # (((Tigers,Big cats)))
@@ -288,6 +357,9 @@ module Asciidoctor
     # whitespace at the beginning of the line
     :leading_blanks   => /^([[:blank:]]*)/,
 
+    # leading parent directory references in path
+    :leading_parent_dirs => /^(?:\.\.\/)*/,
+
     # +   From the Asciidoc User Guide: "A plus character preceded by at
     #     least one space character at the end of a non-blank line forces
     #     a line break. It generates a line break (br) tag for HTML outputs.
@@ -299,11 +371,15 @@ module Asciidoctor
 
     # inline link and some inline link macro
     # FIXME revisit!
-    :link_inline      => %r{(^|link:|\s|>|&lt;|[\(\)\[\]])(\\?(?:https?|ftp)://[^\s\[<]*[^\s.\)\[<])(?:\[((?:\\\]|[^\]])*?)\])?},
+    :link_inline      => %r{(^|link:|\s|>|&lt;|[\(\)\[\]])(\\?(?:https?|ftp)://[^\s\[<]*[^\s.,\[<])(?:\[((?:\\\]|[^\]])*?)\])?},
 
     # inline link macro
     # link:path[label]
-    :link_macro       => /\\?link:([^\s\[]+)(?:\[((?:\\\]|[^\]])*?)\])/,
+    :link_macro       => /\\?(?:link|mailto):([^\s\[]+)(?:\[((?:\\\]|[^\]])*?)\])/,
+
+    # inline email address
+    # doc.writer@asciidoc.org
+    :email_inline     => /[\\>:]?\w[\w.%+-]*@[[:alnum:]][[:alnum:].-]*\.[[:alpha:]]{2,4}\b/, 
 
     # ----
     #:listing          => /^\-{4,}$/,
@@ -323,7 +399,8 @@ module Asciidoctor
     # A. Foo (upperalpha)
     # i. Foo (lowerroman)
     # I. Foo (upperroman)
-    :olist            => /^\s*(\d+\.|[a-z]\.|[ivx]+\)|\.{1,5}) +(.*)$/i,
+    # REVIEW leading space has already been stripped, so may not need in regex
+    :olist            => /^[[:blank:]]*(\.{1,5}|\d+\.|[A-Za-z]\.|[IVXivx]+\))[[:blank:]]+(.*)$/,
 
     # ''' (ruler)
     # <<< (pagebreak)
@@ -394,8 +471,10 @@ module Asciidoctor
     # .Foo   but not  . Foo or ..Foo
     :blk_title        => /^\.([^\s.].*)$/,
 
+    # matches double quoted text, capturing quote char and text (single-line)
     :dbl_quoted       => /^("|)(.*)\1$/,
 
+    # matches double quoted text, capturing quote char and text (multi-line)
     :m_dbl_quoted     => /^("|)(.*)\1$/m,
 
     # == Foo
@@ -417,11 +496,17 @@ module Asciidoctor
     :section_name      => /^((?=.*\w+.*)[^.].*?)$/,
 
     # ======  || ------ || ~~~~~~ || ^^^^^^ || ++++++
-    :section_underline => /^([=\-~^\+])+$/,
+    # TODO build from SECTION_LEVELS keys
+    :section_underline => /^(?:=|-|~|\^|\+)+$/,
+
+    # toc::[]
+    # toc::[levels=2]
+    :toc              => /^toc::\[(.*?)\]$/,
 
     # * Foo (up to 5 consecutive asterisks)
     # - Foo
-    :ulist            => /^ \s* (- | \*{1,5}) \s+ (.*) $/x,
+    # REVIEW leading space has already been stripped, so may not need in regex
+    :ulist            => /^[[:blank:]]*(-|\*{1,5})[[:blank:]]+(.*)$/,
 
     # inline xref macro
     # <<id,reftext>> (special characters have already been escaped, hence the entity references)
@@ -443,15 +528,16 @@ module Asciidoctor
     #:eval_expr        => /^(true|false|("|'|)\{\w+(?:\-\w+)*\}\2|("|')[^\3]*\3|\-?\d+(?:\.\d+)*)[[:blank:]]*(==|!=|<=|>=|<|>)[[:blank:]]*(true|false|("|'|)\{\w+(?:\-\w+)*\}\6|("|')[^\7]*\7|\-?\d+(?:\.\d+)*)$/,
 
     # include::chapter1.ad[]
-    :include_macro    => /^\\?include::([^\[]+)\[\]$/,
+    # include::example.txt[lines=1;2;5..10]
+    :include_macro    => /^\\?include::([^\[]+)\[(.*?)\]$/,
 
     # http://domain
     # https://domain
     # data:info
-    :uri_sniff        => /^[[:alpha:]][[:alnum:].+-]*:/i
-  }
+    :uri_sniff        => /^[[:alpha:]][[:alnum:].+-]*:/i,
 
-  ADMONITION_STYLES = ['NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION']
+    :uri_encode_chars => /[^\w\-.!~*';:@=+$,()\[\]]/
+  }
 
   INTRINSICS = Hash.new{|h,k| STDERR.puts "Missing intrinsic: #{k.inspect}"; "{#{k}}"}.merge(
     {
@@ -493,6 +579,7 @@ module Asciidoctor
   }
 
   SPECIAL_CHARS_PATTERN = /[#{SPECIAL_CHARS.keys.join}]/
+  #SPECIAL_CHARS_PATTERN = /(?:<|>|&(?![[:alpha:]]{2,};|#[[:digit:]]{2,}+;|#x[[:alnum:]]{2,}+;))/
 
   # unconstrained quotes:: can appear anywhere
   # constrained quotes:: must be bordered by non-word characters
@@ -545,33 +632,29 @@ module Asciidoctor
   # order is significant
   REPLACEMENTS = [
     # (C)
-    [/(^|[^\\])\(C\)/, '\1&#169;'], 
+    [/\\?\(C\)/, '&#169;', :none],
     # (R)
-    [/(^|[^\\])\(R\)/, '\1&#174;'],
+    [/\\?\(R\)/, '&#174;', :none],
     # (TM)
-    [/(^|[^\\])\(TM\)/, '\1&#8482;'],
+    [/\\?\(TM\)/, '&#8482;', :none],
     # foo -- bar
-    [/(^|\n| )--( |\n|$)/, '&#8201;&#8212;&#8201;'],
+    [/(^|\n| |\\)--( |\n|$)/, '&#8201;&#8212;&#8201;', :none],
     # foo--bar
-    [/(\w)--(?=\w)/, '\1&#8212;'],
+    [/(\w)\\?--(?=\w)/, '&#8212;', :leading],
     # ellipsis
-    [/(^|[^\\])\.\.\./, '\1&#8230;'],
+    [/\\?\.\.\./, '&#8230;', :leading],
     # single quotes
-    [/(\w)'(\w)/, '\1&#8217;\2'],
-    # escaped single quotes
-    [/(\w)\\'(\w)/, '\1\'\2'],
+    [/(\w)\\?'(\w)/, '&#8217;', :bounding],
     # right arrow ->
-    [/(^|[^\\])-&gt;/, '\1&#8594;'],
+    [/\\?-&gt;/, '&#8594;', :none],
     # right double arrow =>
-    [/(^|[^\\])=&gt;/, '\1&#8658;'],
+    [/\\?=&gt;/, '&#8658;', :none],
     # left arrow <-
-    [/(^|[^\\])&lt;-/, '\1&#8592;'],
+    [/\\?&lt;-/, '&#8592;', :none],
     # right left arrow <=
-    [/(^|[^\\])&lt;=/, '\1&#8656;'],
-    # and so on...
-    
-    # restore entities; TODO needs cleanup
-    [/(^|[^\\])&amp;(#[a-z0-9]+;)/i, '\1&\2']
+    [/\\?&lt;=/, '&#8656;', :none],
+    # restore entities
+    [/\\?(&)amp;((?:[[:alpha:]]+|#[[:digit:]]+|#x[[:alnum:]]+);)/, '', :bounding]
   ]
 
   # Public: Parse the AsciiDoc source input into an Asciidoctor::Document
@@ -587,6 +670,10 @@ module Asciidoctor
   #
   # returns the Asciidoctor::Document
   def self.load(input, options = {}, &block)
+    if (monitor = options.fetch(:monitor, false))
+      start = Time.now
+    end
+
     lines = nil
     if input.is_a?(File)
       options[:attributes] ||= {}
@@ -612,7 +699,19 @@ module Asciidoctor
       raise "Unsupported input type: #{input.class}"
     end
 
-    Document.new(lines, options, &block) 
+    if monitor
+      read_time = Time.now - start
+      start = Time.now
+    end
+
+    doc = Document.new(lines, options, &block) 
+    if monitor
+      parse_time = Time.now - start
+      monitor[:read] = read_time
+      monitor[:parse] = parse_time
+      monitor[:load] = read_time + parse_time
+    end
+    doc
   end
 
   # Public: Parse the contents of the AsciiDoc source file into an Asciidoctor::Document
@@ -658,18 +757,22 @@ module Asciidoctor
   #           see Asciidoctor::Document#initialize for details
   # block   - a callback block for handling include::[] directives
   #
-  # returns nothing if the rendered output String is written to a file,
-  # otherwise the rendered output String is returned
+  # returns the Document object if the rendered result String is written to a
+  # file, otherwise the rendered result String
   def self.render(input, options = {}, &block)
     in_place = options.delete(:in_place) || false
     to_file = options.delete(:to_file)
     to_dir = options.delete(:to_dir)
     mkdirs = options.delete(:mkdirs) || false
+    monitor = options.fetch(:monitor, false)
 
     write_in_place = in_place && input.is_a?(File)
     write_to_target = to_file || to_dir
+    stream_output = !to_file.nil? && to_file.respond_to?(:write)
 
-    raise ArgumentError, ':in_place with input file must not accompany :to_dir or :to_file' if write_in_place && write_to_target
+    if write_in_place && write_to_target
+      raise ArgumentError, 'the option :in_place cannot be used with either the :to_dir or :to_file option'
+    end
 
     if !options.has_key?(:header_footer) && (write_in_place || write_to_target)
       options[:header_footer] = true
@@ -677,21 +780,26 @@ module Asciidoctor
 
     doc = Asciidoctor.load(input, options, &block)
 
-    if write_in_place
+    if to_file == '/dev/null'
+      return doc
+    elsif write_in_place
       to_file = File.join(File.dirname(input.path), "#{doc.attributes['docname']}#{doc.attributes['outfilesuffix']}")
-    elsif write_to_target
+    elsif !stream_output && write_to_target
+      working_dir = options.has_key?(:base_dir) ? File.expand_path(opts[:base_dir]) : File.expand_path(Dir.pwd)
+      # QUESTION should the jail be the working_dir or doc.base_dir???
+      jail = doc.safe >= SafeMode::SAFE ? working_dir : nil
       if to_dir
-        to_dir = doc.normalize_asset_path(to_dir, 'to_dir', false)
+        to_dir = doc.normalize_system_path(to_dir, working_dir, jail, :target_name => 'to_dir', :recover => false)
         if to_file
-          # normalize again, to_file could have dirty bits
-          to_file = doc.normalize_asset_path(File.expand_path(to_file, to_dir), 'to_file', false)
+          to_file = doc.normalize_system_path(to_file, to_dir, nil, :target_name => 'to_dir', :recover => false)
           # reestablish to_dir as the final target directory (in the case to_file had directory segments)
           to_dir = File.dirname(to_file)
         else
           to_file = File.join(to_dir, "#{doc.attributes['docname']}#{doc.attributes['outfilesuffix']}")
         end
       elsif to_file
-        to_file = doc.normalize_asset_path(to_file, 'to_file', false)
+        to_file = doc.normalize_system_path(to_file, working_dir, jail, :target_name => 'to_dir', :recover => false)
+        # establish to_dir as the final target directory (in the case to_file had directory segments)
         to_dir = File.dirname(to_file)
       end
 
@@ -705,11 +813,46 @@ module Asciidoctor
       end
     end
 
+    start = Time.now if monitor
+    output = doc.render
+
+    if monitor
+      render_time = Time.now - start
+      monitor[:render] = render_time
+      monitor[:load_render] = monitor[:load] + render_time
+    end
+
     if to_file
-      File.open(to_file, 'w') {|file| file.write doc.render }
-      nil
+      start = Time.now if monitor
+      if stream_output
+        to_file.write output.rstrip
+        # ensure there's a trailing endline
+        to_file.write "\n"
+      else
+        File.open(to_file, 'w') {|file| file.write output }
+        # these assignments primarily for testing, diagnostics or reporting
+        doc.attributes['outfile'] = outfile = File.expand_path(to_file)
+        doc.attributes['outdir'] = File.dirname(outfile)
+      end
+      if monitor
+        write_time = Time.now - start
+        monitor[:write] = write_time
+        monitor[:total] = monitor[:load_render] + write_time
+      end
+
+      # NOTE document cannot control this behavior if safe >= SafeMode::SERVER
+      if !stream_output && doc.attr?('copycss') &&
+          doc.attr?('linkcss') && DEFAULT_STYLESHEET_KEYS.include?(doc.attr('stylesheet'))
+        Helpers.require_library 'fileutils'
+        outdir = doc.attr('outdir')
+        stylesdir = doc.normalize_system_path(doc.attr('stylesdir'), outdir,
+            doc.safe >= SafeMode::SAFE ? outdir : nil)
+        FileUtils.mkdir_p stylesdir
+        FileUtils.cp DEFAULT_STYLESHEET_PATH, stylesdir, :preserve => true
+      end
+      doc
     else
-      doc.render
+      output
     end
   end
 
@@ -721,8 +864,8 @@ module Asciidoctor
   #           see Asciidoctor::Document#initialize for details
   # block   - a callback block for handling include::[] directives
   #
-  # returns nothing if the rendered output String is written to a file,
-  # otherwise the rendered output String is returned
+  # returns the Document object if the rendered result String is written to a
+  # file, otherwise the rendered result String
   def self.render_file(filename, options = {}, &block)
     Asciidoctor.render(File.new(filename), options, &block)
   end
@@ -750,10 +893,10 @@ module Asciidoctor
   require 'asciidoctor/block'
   require 'asciidoctor/callouts'
   require 'asciidoctor/document'
-  #require 'asciidoctor/errors'
   require 'asciidoctor/inline'
   require 'asciidoctor/lexer'
   require 'asciidoctor/list_item'
+  require 'asciidoctor/path_resolver'
   require 'asciidoctor/reader'
   require 'asciidoctor/renderer'
   require 'asciidoctor/section'