asciidoctor 0.0.5 → 0.0.6

data/README.asciidoc

@@ -0,0 +1,156 @@
+[float]
+Asciidoctor
+===========
+:gitscm-next: https://github.com/github/gitscm-next
+:tilt: https://github.com/rtomayko/tilt
+:freesoftware: http://www.fsf.org/licensing/essays/free-sw.html
+:issues: https://github.com/erebor/asciidoctor/issues
+:gist: https://gist.github.com
+:fork: http://help.github.com/fork-a-repo/
+:branch: http://learn.github.com/p/branching.html
+:pr: http://help.github.com/send-pull-requests/
+:license: https://github.com/erebor/asciidoctor/blob/master/LICENSE
+
+http://github.com/erebor/asciidoctor[Asciidoctor] is a pure-Ruby
+processor for turning
+http://www.methods.co.nz/asciidoc/index.html[AsciiDoc] documents or
+strings into HTML (and, eventually other formats as well...'stay
+tuned!').
+
+Asciidoctor uses simple built-in ERB templates to style the output in
+a way that roughly matches the default HTML output of the native
+Python processor. You can override this behavior by providing
+{tilt}[Tilt]-compatible templates. See the xref:usage[Usage section]
+for more details.
+
+Asciidoctor currently works with Ruby 1.8.7 and 1.9.3, though I don't
+know of any reason it shouldn't work with more exotic Ruby versions,
+and would welcome help in testing that out.
+
+The initial code from which Asciidoctor started was from the
+{gitscm-next}[Git SCM site repo].
+
+== Installation
+
+NOTE: This gem is very immature, and as yet only supports a small
+subset of AsciiDoc features. Thus, you should only use it if you have
+a high tolerance for bugs, failures, and generally bad and intemperate
+behavior.
+
+To install the gem:
+
+ gem install asciidoctor
+
+Or if you prefer bundler:
+
+ bundle install asciidoctor
+
+== Usage
+
+To render a file containing AsciiDoc markup to HTML:
+
+ lines = File.readlines('your_file.asciidoc')
+ doc = Asciidoctor::Document.new(lines)
+ html = doc.render
+ File.open('your_file.html', 'w+') do |file|
+   file.puts html
+ end
+
+To render an AsciiDoc-formatted string:
+
+ doc = Asciidoctor::Document.new("*This* is it.")
+ puts doc.render
+
+Asciidoctor allows you to override the default template used to render
+almost any individual AsciiDoc element. If you provide a directory of
+{tilt}[Tilt]-compatible templates, named in such a way that Asciidoctor
+can figure out which template goes with which element, Asciidoctor will
+use the templates in this directory instead of its built-in templates
+for any elements for which it finds a matching template. It will
+fallback to its default templates for everything else.
+
+ doc = Asciidoctor::Document.new("*This* is it.", :template_dir => 'templates')
+ puts doc.render
+
+The Document and Section templates should begin with `document.` and
+`section.`, respectively. The file extension will depend on which
+Tilt-compatible format you've chosen. For ERB, the template names would be
+`document.html.erb` and `section.html.erb`, for instance. For Haml, they
+would be `document.html.haml` and `section.html.haml`.
+
+Templates for specific elements, like a Paragraph or Anchor, would begin
+with `section_<element>.`. For instance, to override the default Paragraph
+template with an ERB template, put a file called `section_paragraph.html.erb`
+in the template directory you pass in to `Document.new`.
+
+For more usage examples, see the test suite.
+
+== Contributing
+
+In the spirit of {freesoftware}[free software], 'everyone' is
+encouraged to help improve this project.
+
+Here are some ways *you* can contribute:
+
+* by using alpha, beta, and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code ('No patch is too small.' Fix typos, add comments,
+  clean up inconsistent whitespace, etc.)
+* by refactoring code
+* by fixing {issues}[issues]
+* by reviewing patches
+
+== Submitting an Issue
+
+We use the {issues}[GitHub issue tracker] associated with this project
+to track bugs and features.  Before submitting a bug report or feature
+request, check to make sure it hasn't already been submitted. When
+submitting a bug report, please include a {gist}[Gist] that includes
+any details that may help reproduce the bug, including your gem
+version, Ruby version, and operating system.
+
+Most importantly, since Asciidoctor is a text processor, reproducing
+most bugs requires that we have some snippet of text on which
+Asciidoctor exhibits the bad behavior.
+
+An ideal bug report would include a pull request with failing specs.
+
+== Submitting a Pull Request
+
+. {fork}[Fork the repository].
+. {branch}[Create a topic branch].
+. Add tests for your unimplemented feature or bug fix.
+. Run `bundle exec rake`. If your tests pass, return to step 3.
+. Implement your feature or bug fix.
+. Run `bundle exec rake`. If your tests fail, return to step 5.
+. Add documentation for your feature or bug fix.
+. If your changes are not 100% documented, go back to step 7.
+. Add, commit, and push your changes.
+. {pr}[Submit a pull request].
+
+
+== Supported Ruby Versions
+
+This library aims to support the following Ruby implementations:
+
+* Ruby 1.8.7
+* Ruby 1.9.3
+
+If something doesn't work on one of these interpreters, it should be
+considered a bug.
+
+If you would like this library to support another Ruby version, you
+may volunteer to be a maintainer. Being a maintainer entails making
+sure all tests run and pass on that implementation. When something
+breaks on your implementation, you will be personally responsible for
+providing patches in a timely fashion. If critical issues for a
+particular implementation exist at the time of a major release,
+support for that Ruby version may be dropped.
+
+== Copyright
+
+Copyright (c) 2012 Ryan Waldron.
+See {license}[LICENSE] for details.

data/asciidoctor.gemspec

@@ -13,8 +13,8 @@ Gem::Specification.new do |s|
   ## If your rubyforge_project name is different, then edit it and comment out
   ## the sub! line in the Rakefile
   s.name              = 'asciidoctor'
-  s.version           = '0.0.5'
-  s.date              = '2012-12-11'
+  s.version           = '0.0.6'
+  s.date              = '2012-12-17'
   s.rubyforge_project = 'asciidoctor'
 
   ## Make sure your summary is short. The description may be as long
@@ -59,7 +59,7 @@ Gem::Specification.new do |s|
   # = MANIFEST =
   s.files = %w[
     LICENSE
-    README.md
+    README.asciidoc
     Rakefile
     asciidoctor.gemspec
     bin/asciidoctor
@@ -86,8 +86,9 @@ Gem::Specification.new do |s|
     test/headers_test.rb
     test/lexer_test.rb
     test/links_test.rb
-    test/list_elements_test.rb
+    test/lists_test.rb
     test/paragraphs_test.rb
+    test/preamble_test.rb
     test/reader_test.rb
     test/test_helper.rb
     test/text_test.rb

data/lib/asciidoctor.rb

@@ -47,6 +47,14 @@ $:.unshift(File.join(File.dirname(__FILE__), '..', 'vendor'))
 #     file.puts html
 #   end
 module Asciidoctor
+  # The default document type
+  # Can influence markup generated by render templates
+  DEFAULT_DOCTYPE = 'article'
+
+  LIST_CONTEXTS = [:ulist, :olist, :dlist]
+
+  LIST_CONTINUATION = '+'
+
   REGEXP = {
     # [[Foo]]  (also allows, say, [[[]] or [[[Foo[f]], but I don't think it is supposed to (TODO))
     :anchor           => /^\[(\[.+\])\]\s*$/,
@@ -59,14 +67,19 @@ module Asciidoctor
     #     a forced line break. This should be the same regexp as :line_break,
     #     below, but it gets its own entry because readability ftw, even
     #     though repeating regexps ftl.
-    :attr_continue    => /(.*)(?:^|\s)\+$/,
+    :attr_continue    => /^(.*)[[:blank:]]\+[[:blank:]]*$/,
+
+    # An attribute list above a block element
+    #
+    # Can be strictly positional:
+    # [quote, Adam Smith, Wealth of Nations]
+    # Or can have name/value pairs
+    # [NOTE, caption="Good to know"]
+    :attr_list_blk    => /^\[(\w.*)\]$/,
 
     # [[[Foo]]]  (does not suffer quite the same malady as :anchor, but almost. Allows [ but not ] in internal capture
     :biblio           => /\[\[\[([^\]]+)\]\]\]/,
 
-    # [caption="Foo"]
-    :caption          => /^\[caption=\"([^\"]+)\"\]/,
-
     # <1> Foo
     :colist           => /^(\<\d+\>)\s*(.*)/,
 
@@ -76,25 +89,40 @@ module Asciidoctor
     :comment_blk      => /^\/{4,}\s*$/,
 
     # // (and then whatever)
-    :comment          => /^\/\/[^\/]/,
+    :comment          => /^\/\/([^\/]|$)/,
 
     # foo::  ||  foo;;
     # Should be followed by a definition line, e.g.,
     # foo::
     #    That which precedes 'bar' (see also, bar)
-    :dlist            => /^(\s*)(\S.*)(::|;;)\s*$/,
-
+    :dlist            => /^\s*(?:\[\[([^\]]*)\]\])?(\w.*?)(:{2,4}|;;)(\s+(.*))?$/,
+    :dlist_siblings   => {
+                           # (?:.*?[^:])? - a non-capturing group which grabs longest sequence of characters that doesn't end w/ colon
+                           '::' => /^\s*(?:\[\[([^\]]*)\]\])?(\w(?:.*[^:])?)(::)(\s+(.*))?$/,
+                           ':::' => /^\s*(?:\[\[([^\]]*)\]\])?(\w(?:.*[^:])?)(:::)(\s+(.*))?$/,
+                           '::::' => /^\s*(?:\[\[([^\]]*)\]\])?(\w(?:.*[^:])?)(::::)(\s+(.*))?$/,
+                           ';;' => /^\s*(?:\[\[([^\]]*)\]\])?(\w.*)(;;)(\s+(.*))?$/
+                         },
     # ====
     :example          => /^={4,}\s*$/,
 
+    # image::filename.png[Caption]
+    :image_blk        => /^image::(\S+?)\[(.*?)\]$/,
+
     # == Foo
-    # Yields a Level 2 title, so exactly the same as
-    #   Foo
-    #   ~~~
-    # would yield.  match[1] is the == sequence, whose
-    # length determines the level, and match[2] is the
-    # title itself.
-    :level_title      => /^(={2,5})\s+(\S.*)\s*$/,
+    # ^ yields a level 2 title
+    #
+    # == Foo ==
+    # ^ also yields a level 2 title
+    #
+    # both equivalent to this two-line version:
+    # Foo
+    # ~~~
+    #
+    # match[1] is the delimiter, whose length determines the level
+    # match[2] is the title itself
+    # match[3] is an optional repeat of the delimiter, which is dropped
+    :level_title      => /^(={1,5})\s+(\S.*?)\s*(\s\1)?$/,
 
     # ======  || ------ || ~~~~~~ || ^^^^^^ || ++++++
     :line             => /^([=\-~^\+])+\s*$/,
@@ -103,26 +131,14 @@ module Asciidoctor
     #     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.
     #
-    #     This is the correct regexp to match what the User Guide actually
-    #     says to do:
-    #     :line_break        => /^(.*(?:\S+)+.*)\s\+$/,
-    #
-    # But the regexp we're using (below), is what asciidoc *actually*
-    # does for HTML output, courtesy of the default html4.conf file (under
-    # the [replacements2] section).
-    #
     # +      (would not match because there's no space before +)
     #  +     (would match and capture '')
     # Foo +  (would and capture 'Foo')
-    :line_break       => /^(.*)\s\+$/,
+    :line_break       => /([[:blank:]])\+[[:blank:]]*$/,
 
     # ----
     :listing          => /^\-{4,}\s*$/,
 
-    # [source, ruby]
-    # Treats the next paragraph as a :listing block
-    :listing_source   => /^\[source,\s*([^\]]+)\]\s*$/,
-
     # ....
     :lit_blk          => /^\.{4,}\s*$/,
 
@@ -132,9 +148,6 @@ module Asciidoctor
     # "Wooble"  ||  Wooble
     :name             => /^(["A-Za-z].*)\s*$/,  # I believe this fails to require " chars to be paired (TODO)
 
-    # [NOTE]
-    :note             => /^\[NOTE\]\s*$/,
-
     # --
     :oblock           => /^\-\-\s*$/,
 
@@ -158,12 +171,11 @@ module Asciidoctor
     :title            => /^\.([^\s\.].*)\s*$/,
 
     # * Foo  ||  - Foo
-    :ulist            => /^ \s* (- | \*{1,5}) \s+ (.*) $/x,
-
-    # [verse]
-    :verse            => /^\[verse\]\s*$/
+    :ulist            => /^ \s* (- | \*{1,5}) \s+ (.*) $/x
   }
 
+  ADMONITION_STYLES = ['NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION']
+
   INTRINSICS = Hash.new{|h,k| STDERR.puts "Missing intrinsic: #{k.inspect}"; "{#{k}}"}.merge(
     'startsb'    => '[',
     'endsb'      => ']',

data/lib/asciidoctor/block.rb

@@ -9,6 +9,12 @@ class Asciidoctor::Block
   # Public: Get the Symbol context for this section block.
   attr_reader :context
 
+  # Public: Create alias for context to be consistent w/ AsciiDoc
+  alias :blockname :context
+
+  # Public: Get the Hash of attributes for this block
+  attr_reader :attributes
+
   # Public: Get the Array of sub-blocks for this section block.
   attr_reader :blocks
 
@@ -17,6 +23,7 @@ class Asciidoctor::Block
 
   # Public: Get/Set the String section anchor name.
   attr_accessor :anchor
+  alias :id :anchor
 
   # Public: Get/Set the Integer block level (for nested elements, like
   # list elements).
@@ -41,7 +48,7 @@ class Asciidoctor::Block
     @parent = parent
     @context = context
     @buffer = buffer
-
+    @attributes = {}
     @blocks = []
   end
 
@@ -51,9 +58,23 @@ class Asciidoctor::Block
     @document = (@parent.is_a?(Asciidoctor::Document) ? @parent : @parent.document)
   end
 
+  def attr(name, default = nil)
+    default.nil? ? @attributes.fetch(name.to_s, self.document.attr(name)) :
+        @attributes.fetch(name.to_s, self.document.attr(name, default))
+  end
+
+  def attr?(name)
+    @attributes.has_key?(name.to_s) || self.document.attr?(name)
+  end
+
+  def update_attributes(attributes)
+    @attributes.update(attributes)
+  end
+
   # Public: Get the Asciidoctor::Renderer instance being used for the ancestor
   # Asciidoctor::Document instance.
   def renderer
+    # wouldn't @parent.renderer work here? I believe so
     document.renderer
   end
 
@@ -128,48 +149,30 @@ class Asciidoctor::Block
   # * super/sub script
   def content
 
-    Asciidoctor.debug "For the record, buffer is:"
-    Asciidoctor.debug @buffer.inspect
+    #Asciidoctor.debug "For the record, buffer is:"
+    #Asciidoctor.debug @buffer.inspect
 
     case @context
-    when :dlist
-      @buffer.map do |dt, dd|
-        if !dt.anchor.nil? && !dt.anchor.empty?
-          html_dt = "<a id=#{dt.anchor}></a>" + htmlify(dt.content)
-        else
-          html_dt = htmlify(dt.content)
-        end
-        if dd.content.empty?
-          html_dd = ''
-        else
-          html_dd = "<p>#{htmlify(dd.content)}</p>"
-        end
-        html_dd += dd.blocks.map{|block| block.render}.join
-
-        [html_dt, html_dd]
-      end
-    when :oblock, :quote
+    when :preamble, :oblock, :example, :sidebar
       blocks.map{|block| block.render}.join
-    when :olist, :colist
+    when :colist
       @buffer.map do |li|
-        htmlify(li.content) + li.blocks.map{|block| block.render}.join
-      end
-    when :ulist
-      @buffer.map do |element|
-        if element.is_a? Asciidoctor::ListItem
-          element.content = sub_attributes(element.content)
-        end
-        # TODO - not sure why tests work the same whether or not this is commented out.
-        # I think that I am likely not yet testing unordered list items with no block
-        # content. Still and all, it seems like this should be all done by list_item.render .
-        element.render # + element.blocks.map{|block| block.render}.join
+        htmlify(li.text) + li.blocks.map{|block| block.render}.join
       end
+    # lists get iterated in template
+    # list items recurse into this block when their text and content methods are called
+    when :ulist, :olist, :dlist
+      @buffer
     when :listing
-      @buffer.map{|l| CGI.escapeHTML(l).gsub(/(<\d+>)/,'<b>\1</b>')}.join
+      sub_special_chars(@buffer.join).gsub(/&lt;(\d+)&gt;/, '<b>\1</b>')
     when :literal
-      htmlify( @buffer.join.gsub( '*', '{asterisk}' ).gsub( '\'', '{apostrophe}' ))
-    when :verse
-      htmlify( sub_attributes(@buffer).map{ |l| l.strip }.join( "\n" ) )
+      sub_special_chars(@buffer.join)
+    when :quote, :verse, :admonition
+      if !@buffer.nil?
+        htmlify(sub_attributes(@buffer).map{ |l| l.strip }.join( "\n" ))
+      else
+        blocks.map{|block| block.render}.join
+      end
     else
       lines = sub_attributes(@buffer).map do |line|
         line.strip
@@ -195,9 +198,9 @@ class Asciidoctor::Block
       f = sub_special_chars(line)
       # gsub! doesn't have lookbehind, so we have to capture and re-insert
       f = f.gsub(/ (^|[^\\]) \{ (\w([\w\-_]+)?\w) \} /x) do
-        if self.document.defines.has_key?($2)
-          # Substitute from user defines first
-          $1 + self.document.defines[$2]
+        if self.document.attributes.has_key?($2)
+          # Substitute from user attributes first
+          $1 + self.document.attributes[$2]
         elsif Asciidoctor::INTRINSICS.has_key?($2)
           # Then do intrinsics
           $1 + Asciidoctor::INTRINSICS[$2]
@@ -215,7 +218,7 @@ class Asciidoctor::Block
       Asciidoctor.debug "#{__method__} -> Processed line: #{f}"
       f
     end
-    Asciidoctor.debug "#{__method__} -> result looks like #{result.inspect}"
+    #Asciidoctor.debug "#{__method__} -> result looks like #{result.inspect}"
     result.reject! {|l| l =~ /\{ZZZZZ\}/}
 
     if return_string
@@ -242,7 +245,7 @@ class Asciidoctor::Block
         end
       end
     end
-    Asciidoctor.debug "#{__method__} -> result looks like #{result.inspect}"
+    #Asciidoctor.debug "#{__method__} -> result looks like #{result.inspect}"
     result.reject! {|l| l =~ /\{ZZZZZ\}/}
 
     if return_string
@@ -251,6 +254,20 @@ class Asciidoctor::Block
     result
   end
 
+  # Public: Append a sub-block to this section block
+  #
+  # block - The new sub-block.
+  #
+  #   block = Block.new(parent, :preamble)
+  #
+  #   block << Block.new(block, :paragraph, 'p1')
+  #   block << Block.new(block, :paragraph, 'p2')
+  #   block.blocks
+  #   => ["p1", "p2"]
+  def <<(block)
+    @blocks << block
+  end
+
   private
 
   # Private: Return a String HTML version of the source string, with
@@ -284,7 +301,7 @@ class Asciidoctor::Block
       end
 
       html.gsub!(Asciidoctor::REGEXP[:biblio], '<a name="\1">[\1]</a>')
-      html.gsub!(Asciidoctor::REGEXP[:ruler], '<hr>\n')
+      html.gsub!(Asciidoctor::REGEXP[:ruler], "<hr>\n")
       html.gsub!(/``([^`']*)''/m, '&ldquo;\1&rdquo;')
       html.gsub!(/(?:\s|^)`([^`']*)'/m, '&lsquo;\1&rsquo;')