[float]
Asciidoctor
===========
:asciidoctor: http://github.com/erebor/asciidoctor
:asciidoc: http://www.methods.co.nz/asciidoc/index.html
:gitscm-next: https://github.com/github/gitscm-next
:asciidoctorseed: https://github.com/github/gitscm-next/commits/master/lib/asciidoc.rb
:templates: https://github.com/erebor/asciidoctor/blob/master/lib/asciidoctor/render_templates.rb
: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

{asciidoctor}[Asciidoctor] is a pure-Ruby processor for turning
{asciidoc}[AsciiDoc] documents or strings into HTML (and, eventually
other formats as well...'stay tuned!').

image::https://travis-ci.org/erebor/asciidoctor.png?branch=master["Build Status", link="https://travis-ci.org/erebor/asciidoctor"]

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]. Refer to commit history of
{asciidoctorseed}[asciidoc.rb] to view the initial contributions.

== Installation

NOTE: This gem is very immature, and as yet only supports a small subset
of AsciiDoc features (but it's getting better!). 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 {templates}[built-in templates]
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 is used by Tilt to
determine which view framework it will use to use to render the
template. For instance, if you want to write the template in ERB, you'd
name these two templates `document.html.erb` and `section.html.erb`. To
use Haml, you'd name them `document.html.haml` and `section.html.haml`.

Templates for block elements, like a Paragraph or Sidebar, would begin
with `block_<style>.`. For instance, to override the default Paragraph
template with an ERB template, put a file named
`block_paragraph.html.erb` in the template directory you pass to the
`Document` constructor using the `template_dir` option.

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.

// vim: tw=72