asciidoctor 0.1.4 → 1.5.0

data/Rakefile

@@ -1,165 +1,122 @@
-require 'rubygems'
-require 'rake'
-require 'date'
-
-#############################################################################
-#
-# Helper functions
-#
-#############################################################################
-
-def name
-  @name ||= Dir['*.gemspec'].first.split('.').first
-end
-
-def version
-  line = File.read("lib/#{name}/version.rb")[/^\s*VERSION\s*=\s*.*/]
-  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
-end
-
-def date
-  Date.today.to_s
-end
-
-def rubyforge_project
-  name
-end
-
-def gemspec_file
-  "#{name}.gemspec"
-end
-
-def gem_file
-  "#{name}-#{version}.gem"
+require File.expand_path '../lib/asciidoctor/version', __FILE__
+
+def prepare_test_env
+  # rather than hardcoding gc settings in test task,
+  # could use https://gist.github.com/benders/788695
+  ENV['RUBY_GC_MALLOC_LIMIT'] = 128_000_000.to_s
+  ENV['RUBY_GC_OLDMALLOC_LIMIT'] = 128_000_000.to_s
+  if RUBY_VERSION >= '2.1'
+    ENV['RUBY_GC_HEAP_INIT_SLOTS'] = 800_000.to_s
+    ENV['RUBY_GC_HEAP_FREE_SLOTS'] = 800_000.to_s
+    ENV['RUBY_GC_HEAP_GROWTH_MAX_SLOTS'] = 250_000.to_s
+    ENV['RUBY_GC_HEAP_GROWTH_FACTOR'] = 1.25.to_s
+  else
+    ENV['RUBY_FREE_MIN'] = 800_000.to_s
+  end
 end
 
-def replace_header(head, header_name)
-  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+begin
+  require 'rake/testtask'
+  Rake::TestTask.new(:test) do |test|
+    prepare_test_env
+    puts "LANG: #{ENV['LANG']}"
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+    test.warning = true
+  end
+  task :default => :test
+rescue LoadError
 end
 
-#############################################################################
-#
-# Standard tasks
-#
-#############################################################################
-
-task :default => :test
-
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  puts "LANG: #{ENV['LANG']}"
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/*_test.rb'
-  test.warning = true
-  test.verbose = true
+=begin
+# Run tests with Encoding.default_external set to US-ASCII
+begin
+  Rake::TestTask.new(:test_us_ascii) do |test|
+    prepare_test_env
+    puts "LANG: #{ENV['LANG']}"
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.ruby_opts << '-EUS-ASCII' if RUBY_VERSION >= '1.9'
+    test.verbose = true
+    test.warning = true
+  end
+rescue LoadError
 end
+=end
 
-# Run tests with Encoding::default_external set to US-ASCII
-Rake::TestTask.new(:test_us_ascii) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/*_test.rb'
-  test.warning = true
-  test.verbose = true
-  test.ruby_opts << '-EUS-ASCII' if RUBY_VERSION >= '1.9'
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features) do |t|
+  end
+rescue LoadError
 end
 
-desc "Generate RCov test coverage and open in your browser"
-task :coverage do
-  require 'rcov'
-  sh "rm -fr coverage"
-  sh "rcov test/test_*.rb"
-  sh "open coverage/index.html"
+namespace :test do
+  desc 'Run unit and feature tests'
+  task :all => [:test,:features]
 end
 
+=begin
 begin
   require 'rdoc/task'
   RDoc::Task.new do |rdoc|
     rdoc.rdoc_dir = 'rdoc'
-    rdoc.title = "#{name} #{version}"
+    rdoc.title = "Asciidoctor #{Asciidoctor::VERSION}"
     rdoc.markup = 'tomdoc' if rdoc.respond_to?(:markup)
-    rdoc.rdoc_files.include('README*')
-    rdoc.rdoc_files.include('lib/**/*.rb')
+    rdoc.rdoc_files.include('LICENSE.adoc', 'lib/**/*.rb')
   end
 rescue LoadError
 end
+=end
 
-desc "Open an irb session preloaded with this library"
-task :console do
-  sh "irb -rubygems -r ./lib/#{name}.rb"
-end
-
-#############################################################################
-#
-# Custom tasks (add your own tasks here)
-#
-#############################################################################
-
-
-
-#############################################################################
-#
-# Packaging tasks
-#
-#############################################################################
-
-desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
-task :release => :build do
-  unless `git branch` =~ /^\* master$/
-    puts "You must be on the master branch to release!"
-    exit!
+begin
+  require 'yard'
+  require 'yard-tomdoc'
+  require './lib/asciidoctor'
+  require './lib/asciidoctor/extensions'
+
+  # Prevent YARD from breaking command statements in literal paragraphs
+  class CommandBlockPostprocessor < Asciidoctor::Extensions::Postprocessor
+    def process document, output
+      output.gsub(/<pre>\$ (.+?)<\/pre>/m, '<pre class="command code"><span class="const">$</span> \1</pre>')
+    end
+  end
+  Asciidoctor::Extensions.register do
+    postprocessor CommandBlockPostprocessor
   end
-  sh "git commit --allow-empty -a -m 'Release #{version}'"
-  sh "git tag v#{version}"
-  sh "git push origin master"
-  sh "git push origin v#{version}"
-  sh "gem push pkg/#{name}-#{version}.gem"
-end
 
-desc "Build #{gem_file} into the pkg directory"
-task :build => :gemspec do
-  sh "mkdir -p pkg"
-  sh "gem build #{gemspec_file}"
-  sh "mv #{gem_file} pkg"
+  # register .adoc extension for AsciiDoc markup helper
+  YARD::Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS[:asciidoc] = %w(adoc)
+  YARD::Rake::YardocTask.new do |yard|
+    yard.files = %w(
+        lib/**/*.rb
+        -
+        CHANGELOG.adoc
+        LICENSE.adoc
+    )
+    # --no-highlight enabled to prevent verbatim blocks in AsciiDoc that begin with $ from being dropped
+    # need to patch htmlify method to not attempt to syntax highlight blocks (or fix what's wrong)
+    yard.options = (IO.readlines '.yardopts').map {|l| l.chomp.delete('"').split ' ', 2 }.flatten
+  end
+rescue LoadError
 end
 
-desc "Generate #{gemspec_file}"
-task :gemspec => :validate do
-  # read spec file and split out manifest section
-  spec = File.read(gemspec_file)
-  head, manifest, tail = spec.split("  # = MANIFEST =\n")
-
-  # replace name version and date
-  replace_header(head, :name)
-  replace_header(head, :version)
-  replace_header(head, :date)
-  #comment this out if your rubyforge_project has a different name
-  replace_header(head, :rubyforge_project)
+begin
+  require 'bundler/gem_tasks'
 
-  # determine file list from git ls-files
-  files = `git ls-files`.
-    split("\n").
-    sort.
-    reject { |file| file =~ /^\./ }.
-    reject { |file| file =~ /^(rdoc|pkg)/ }.
-    map { |file| "    #{file}" }.
-    join("\n")
+  # Enhance the release task to create an explicit commit for the release
+  Rake::Task[:release].enhance [:commit_release]
 
-  # piece file back together and write
-  manifest = "  s.files = %w[\n#{files}\n  ]\n"
-  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
-  File.open(gemspec_file, 'w') { |io| io.write(spec) }
-  puts "Updated #{gemspec_file}"
+  # NOTE you don't need to push after updating version and committing locally
+  task :commit_release do
+    Bundler::GemHelper.new.send(:guard_clean)
+    sh "git commit --allow-empty -a -m 'Release #{Asciidoctor::VERSION}'"
+  end
+rescue LoadError
 end
 
-desc "Validate #{gemspec_file}"
-task :validate do
-  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
-  unless libfiles.empty?
-    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
-    exit!
-  end
-  unless Dir['VERSION*'].empty?
-    puts "A `VERSION` file at root level violates Gem best practices."
-    exit!
-  end
+desc 'Open an irb session preloaded with this library'
+task :console do
+  sh 'bundle console', :verbose => false
 end

data/benchmark/benchmark.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/env ruby
+
+=begin
+
+Use this script to monitor changes in performance when making code changes to Asciidoctor.
+
+ $ ruby benchmark.rb <benchmark-name> <repeat>
+
+The most common benchmark is the userguide-loop.
+It will download the AsciiDoc User Guide automatically the first time, then convert it in memory.
+Running it 10 times provides a good picture.
+
+ $ ruby benchmark.rb userguide-loop 10
+
+Only worry about the relative change to the numbers before and after the code change.
+Absolute times are highly dependent on the capabilities of the machine the the version of Ruby.
+
+To get the best results under MRI, tune Ruby using environment variables as follows:
+
+.Ruby < 2.1
+ $ RUBY_GC_MALLOC_LIMIT=90000000 RUBY_FREE_MIN=650000 ruby benchmark.rb userguide-loop 10
+
+.Ruby >= 2.1
+ $ RUBY_GC_MALLOC_LIMIT=128000000 RUBY_GC_OLDMALLOC_LIMIT=128000000 RUBY_GC_HEAP_INIT_SLOTS=800000 RUBY_GC_HEAP_FREE_SLOTS=800000 RUBY_GC_HEAP_GROWTH_MAX_SLOTS=250000 RUBY_GC_HEAP_GROWTH_FACTOR=1.5 ruby benchmark.rb userguide-loop 10
+
+Asciidoctor starts with ~ 12,500 objects, adds ~ 300,000 each run, so tune RUBY_GC_HEAP_* accordingly
+
+Execute Ruby using the `--disable=gems` flag to speed up the initial load time, as shown below:
+
+ $ ruby --disable=gems ...
+
+=end
+
+require 'benchmark'
+include Benchmark
+
+bench = ARGV[0]
+$repeat = ARGV[1].to_i || 10000
+
+if bench.nil?
+  raise 'You must specify a benchmark to run.'
+end
+
+def fetch_userguide
+  require 'open-uri'
+  userguide_uri = 'https://raw.githubusercontent.com/asciidoc/asciidoc/d43faae38c4a8bf366dcba545971da99f2b2d625/doc/asciidoc.txt'
+  customers_uri = 'https://raw.githubusercontent.com/asciidoc/asciidoc/d43faae38c4a8bf366dcba545971da99f2b2d625/doc/customers.csv'
+  userguide_content = open(userguide_uri) {|fd2| fd2.read }
+  customers_content = open(customers_uri) {|fd2| fd2.read }
+  File.open('sample-data/userguide.adoc', 'w') {|fd1| fd1.write userguide_content }
+  File.open('sample-data/customers.csv', 'w') {|fd1| fd1.write customers_content }
+end
+
+case bench
+
+=begin
+# benchmark template
+
+when 'name'
+
+  sample = 'value'
+
+  Benchmark.bmbm(12) {|bm|
+    bm.report('operation a') { $repeat.times { call_a_on sample } }
+    bm.report('operation b') { $repeat.times { call_b_on sample } }
+  }
+=end
+
+when 'userguide'
+  require '../lib/asciidoctor.rb'
+  Asciidoctor::Compliance.markdown_syntax = false
+  Asciidoctor::Compliance.shorthand_property_syntax = false if Asciidoctor::VERSION > '0.1.4'
+  sample_file = ENV['BENCH_TEST_FILE'] || 'sample-data/userguide.adoc'
+  backend = ENV['BENCH_BACKEND'] || 'html5'
+  fetch_userguide if sample_file == 'sample-data/userguide.adoc' && !(File.exist? sample_file)
+  result = Benchmark.bmbm {|bm|
+    bm.report(%(Convert #{sample_file} (x#{$repeat}))) {
+      $repeat.times {
+        Asciidoctor.render_file sample_file, :backend => backend, :safe => Asciidoctor::SafeMode::SAFE, :eruby => 'erubis', :header_footer => true, :to_file => false, :attributes => {'linkcss' => '', 'toc' => nil, 'numbered' => nil, 'icons' => nil, 'compat-mode' => 'legacy'}
+      }
+    }
+  }
+  # prints average for real run
+  puts %(>avg: #{result.first.real / $repeat})
+
+when 'userguide-loop'
+  require '../lib/asciidoctor.rb'
+  GC.start
+  Asciidoctor::Compliance.markdown_syntax = false
+  Asciidoctor::Compliance.shorthand_property_syntax = false if Asciidoctor::VERSION > '0.1.4'
+  sample_file = ENV['BENCH_TEST_FILE'] || 'sample-data/userguide.adoc'
+  backend = ENV['BENCH_BACKEND'] || 'html5'
+  fetch_userguide if sample_file == 'sample-data/userguide.adoc' && !(File.exist? sample_file)
+
+  best = nil
+  2.times.each do
+    outer_start = Time.now
+    (1..$repeat).each do
+      inner_start = Time.now
+      Asciidoctor.render_file sample_file, :backend => backend, :safe => Asciidoctor::SafeMode::SAFE, :eruby => 'erubis', :header_footer => true, :to_file => false, :attributes => {'linkcss' => '', 'toc' => nil, 'numbered' => nil, 'icons' => nil, 'compat-mode' => 'legacy'}
+      puts (elapsed = Time.now - inner_start)
+      best = (best ? [best, elapsed].min : elapsed)
+    end
+    puts %(Run Total: #{Time.now - outer_start})
+  end
+  puts %(Best Time: #{best})
+
+when 'mdbasics-loop'
+  require '../lib/asciidoctor.rb'
+  GC.start
+  sample_file = ENV['BENCH_TEST_FILE'] || 'sample-data/userguide.adoc'
+  backend = ENV['BENCH_BACKEND'] || 'html5'
+
+  best = nil
+  2.times do
+    outer_start = Time.now
+    (1..$repeat).each do
+      inner_start = Time.now
+      Asciidoctor.render_file sample_file, :backend => backend, :safe => Asciidoctor::SafeMode::SAFE, :header_footer => false, :to_file => false, :attributes => {'linkcss' => '', 'idprefix' => '', 'idseparator' => '-', 'showtitle' => ''}
+      puts (elapsed = Time.now - inner_start)
+      best = (best ? [best, elapsed].min : elapsed)
+    end
+    puts %(Run Total: #{Time.now - outer_start})
+  end
+  puts %(Best Time: #{best})
+
+end

data/benchmark/sample-data/mdbasics.adoc

@@ -0,0 +1,334 @@
+// converted to AsciiDoc from https://github.com/gettalong/kramdown/blob/master/benchmark/mdbasics.text
+# Markdown: Basics
+John Gruber
+:s: link:/projects/markdown/syntax
+:d: link:/projects/markdown/dingus
+:src: link:/projects/markdown/basics.text
+
+++++
+<ul id="ProjectSubmenu">
+    <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
+    <li><a class="selected" title="Markdown Basics">Basics</a></li>
+    <li><a href="/projects/markdown/syntax" title="Markdown Syntax Documentation">Syntax</a></li>
+    <li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
+    <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
+</ul>
+++++
+
+## Getting the Gist of Markdown's Formatting Syntax
+
+This page offers a brief overview of what it's like to use Markdown.
+The {s}[syntax page] provides complete, detailed documentation for
+every feature, but Markdown should be very easy to pick up simply by
+looking at a few examples of it in action. The examples on this page
+are written in a before/after style, showing example syntax and the
+HTML output produced by Markdown.
+
+It's also helpful to simply try Markdown out; the {d}[Dingus] is a
+web application that allows you type your own Markdown-formatted text
+and translate it to XHTML.
+
+NOTE: This document is itself written using Markdown; you
+can {src}[see the source for it by adding \'.text' to the URL].
+
+### Paragraphs, Headers, Blockquotes
+
+A paragraph is simply one or more consecutive lines of text, separated
+by one or more blank lines. (A blank line is any line that looks like a
+blank line -- a line containing nothing spaces or tabs is considered
+blank.) Normal paragraphs should not be intended with spaces or tabs.
+
+Markdown offers two styles of headers: _Setext_ and _atx_.
+Setext-style headers for +<h1>+ and +<h2>+ are created by
+"underlining" with equal signs (+=+) and hyphens (+-+), respectively.
+To create an atx-style header, you put 1-6 hash marks (+#+) at the
+beginning of the line -- the number of hashes equals the resulting
+HTML header level.
+
+Blockquotes are indicated using email-style \'+>+' angle brackets.
+
+.Markdown:
+[listing]
+....
+A First Level Header
+====================
+
+A Second Level Header
+---------------------
+
+Now is the time for all good men to come to
+the aid of their country. This is just a
+regular paragraph.
+
+The quick brown fox jumped over the lazy
+dog's back.
+
+### Header 3
+
+> This is a blockquote.
+> 
+> This is the second paragraph in the blockquote.
+>
+> ## This is an H2 in a blockquote
+....
+
+.Output:
+....
+<h1>A First Level Header</h1>
+
+<h2>A Second Level Header</h2>
+
+<p>Now is the time for all good men to come to
+the aid of their country. This is just a
+regular paragraph.</p>
+
+<p>The quick brown fox jumped over the lazy
+dog's back.</p>
+
+<h3>Header 3</h3>
+
+<blockquote>
+    <p>This is a blockquote.</p>
+    
+    <p>This is the second paragraph in the blockquote.</p>
+    
+    <h2>This is an H2 in a blockquote</h2>
+</blockquote>
+....
+
+### Phrase Emphasis
+
+Markdown uses asterisks and underscores to indicate spans of emphasis.
+
+.Markdown:
+----
+Some of these words *are emphasized*.
+Some of these words _are emphasized also_.
+
+Use two asterisks for **strong emphasis**.
+Or, if you prefer, __use two underscores instead__.
+----
+
+.Output:
+....
+<p>Some of these words <em>are emphasized</em>.
+Some of these words <em>are emphasized also</em>.</p>
+
+<p>Use two asterisks for <strong>strong emphasis</strong>.
+Or, if you prefer, <strong>use two underscores instead</strong>.</p>
+....
+
+### Lists
+
+Unordered (bulleted) lists use asterisks, pluses, and hyphens (+*+,
++++, and +-+) as list markers. These three markers are
+interchangable; this:
+
+----
+*   Candy.
+*   Gum.
+*   Booze.
+----
+
+this:
+
+----
++   Candy.
++   Gum.
++   Booze.
+----
+
+and this:
+
+----
+-   Candy.
+-   Gum.
+-   Booze.
+----
+
+all produce the same output:
+
+....
+<ul>
+<li>Candy.</li>
+<li>Gum.</li>
+<li>Booze.</li>
+</ul>
+....
+
+Ordered (numbered) lists use regular numbers, followed by periods, as
+list markers:
+
+----
+1.  Red
+2.  Green
+3.  Blue
+----
+
+.Output:
+....
+<ol>
+<li>Red</li>
+<li>Green</li>
+<li>Blue</li>
+</ol>
+....
+
+If you put blank lines between items, you'll get +<p>+ tags for the
+list item text. You can create multi-paragraph list items by indenting
+the paragraphs by 4 spaces or 1 tab:
+
+----
+*   A list item.
+
+    With multiple paragraphs.
+
+*   Another item in the list.
+----
+
+.Output:
+....
+<ul>
+<li><p>A list item.</p>
+<p>With multiple paragraphs.</p></li>
+<li><p>Another item in the list.</p></li>
+</ul>
+....
+
+### Links
+
+Markdown supports two styles for creating links: _inline_ and
+_reference_. With both styles, you use square brackets to delimit the
+text you want to turn into a link.
+
+Inline-style links use parentheses immediately after the link text.
+For example:
+
+----
+This is an [example link](http://example.com/).
+----
+
+.Output:
+....
+<p>This is an <a href="http://example.com/">
+example link</a>.</p>
+....
+
+Optionally, you may include a title attribute in the parentheses:
+
+----
+This is an [example link](http://example.com/ "With a Title").
+----
+
+.Output:
+....
+<p>This is an <a href="http://example.com/" title="With a Title">
+example link</a>.</p>
+....
+
+Reference-style links allow you to refer to your links by names, which
+you define elsewhere in your document:
+
+----
+I get 10 times more traffic from [Google][1] than from
+[Yahoo][2] or [MSN][3].
+
+[1]: http://google.com/        "Google"
+[2]: http://search.yahoo.com/  "Yahoo Search"
+[3]: http://search.msn.com/    "MSN Search"
+----
+
+.Output:
+....
+<p>I get 10 times more traffic from <a href="http://google.com/"
+title="Google">Google</a> than from <a href="http://search.yahoo.com/"
+title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
+title="MSN Search">MSN</a>.</p>
+....
+
+The title attribute is optional. Link names may contain letters,
+numbers and spaces, but are _not_ case sensitive:
+
+----
+I start my morning with a cup of coffee and
+[The New York Times][NY Times].
+
+[ny times]: http://www.nytimes.com/
+----
+
+.Output:
+....
+<p>I start my morning with a cup of coffee and
+<a href="http://www.nytimes.com/">The New York Times</a>.</p>
+....
+
+### Images
+
+Image syntax is very much like link syntax.
+
+.Inline (titles are optional):
+----
+![alt text](/path/to/img.jpg "Title")
+----
+
+.Reference-style:
+----
+![alt text][id]
+
+[id]: /path/to/img.jpg "Title"
+----
+
+Both of the above examples produce the same output:
+
+....
+<img src="/path/to/img.jpg" alt="alt text" title="Title" />
+....
+
+### Code
+
+In a regular paragraph, you can create code span by wrapping text in
+backtick quotes. Any ampersands (+&+) and angle brackets (+<+ or
++>+) will automatically be translated into HTML entities. This makes
+it easy to use Markdown to write about HTML example code:
+
+----
+I strongly recommend against using any `<blink>` tags.
+
+I wish SmartyPants used named entities like `&mdash;`
+instead of decimal-encoded entites like `&#8212;`.
+----
+
+.Output:
+....
+<p>I strongly recommend against using any
+<code>&lt;blink&gt;</code> tags.</p>
+
+<p>I wish SmartyPants used named entities like
+<code>&amp;mdash;</code> instead of decimal-encoded
+entites like <code>&amp;#8212;</code>.</p>
+....
+
+To specify an entire block of pre-formatted code, indent every line of
+the block by 4 spaces or 1 tab. Just like with code spans, +&+, +<+,
+and +>+ characters will be escaped automatically.
+
+.Markdown:
+----
+If you want your page to validate under XHTML 1.0 Strict,
+you've got to put paragraph tags in your blockquotes:
+
+    <blockquote>
+        <p>For example.</p>
+    </blockquote>
+----
+
+.Output:
+....
+<p>If you want your page to validate under XHTML 1.0 Strict,
+you've got to put paragraph tags in your blockquotes:</p>
+
+<pre><code>&lt;blockquote&gt;
+    &lt;p&gt;For example.&lt;/p&gt;
+&lt;/blockquote&gt;
+</code></pre>
+....