<commit_before>Asciidoctor
===========
:asciidoctor: http://asciidoctor.org
:asciidoctor-source: http://github.com/erebor/asciidoctor
:asciidoc: http://asciidoc.org
:gitscm-next: https://github.com/github/gitscm-next
:asciidoctor-seed: https://github.com/github/gitscm-next/commits/master/lib/asciidoc.rb
:templates: https://github.com/erebor/asciidoctor/blob/master/lib/asciidoctor/backends
: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
:idprefix:

{asciidoctor}[Asciidoctor] is a pure Ruby processor for converting
{asciidoc}[AsciiDoc] source files and strings into HTML 5, DocBook 4.5
and other formats.

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

Asciidoctor uses a set of built-in ERB templates to render the document
to HTML 5 or DocBook 4.5. We've matched the rendered output as close as
possible to the default 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 (read as 'tested') with Ruby 1.8.7, Ruby
1.9.3 and JRuby 1.7.2 (on Linux, Mac and Windows). We expect it will
work with other versions of Ruby as well and would welcome help in
testing it out.

The initial code from which Asciidoctor started emerged from the
{gitscm-next}[Git SCM site repo]. Refer to commit history of
{asciidoctor-seed}[asciidoc.rb] to view the initial contributions and
individual contributors.

The source code can now be found in the {asciidoctor-source}[Asciidoctor
source repository] on GitHub.

== Installation

NOTE: We are working hard to make Asciidoctor a drop-in replacement for
AsciiDoc. We're very close, with nearly 600 tests that ensure
compatibility. The march is on towards full compliance and beyond.

To install the gem:

 gem install asciidoctor

Or if you prefer bundler:

 bundle install asciidoctor

== Usage

To use Asciidoctor in your application, you first need to require the
library:

 require 'asciidoctor'

With that in place, you can start processing AsciiDoc documents.

.Loading a document
To parse a file into an `Asciidoctor::Document` object:

 doc = Asciidoctor.load_file('your_file.asciidoc')

You can get information about the document:

 puts doc.doctitle
 puts doc.attributes

More than likely, you want to just render the document.

.Rendering files
To render a file containing AsciiDoc markup to HTML 5:<commit_msg>Updating the README to reflect the cli usage<commit_after>Asciidoctor
===========
:asciidoctor: http://asciidoctor.org
:asciidoctor-source: http://github.com/erebor/asciidoctor
:asciidoc: http://asciidoc.org
:gitscm-next: https://github.com/github/gitscm-next
:asciidoctor-seed: https://github.com/github/gitscm-next/commits/master/lib/asciidoc.rb
:templates: https://github.com/erebor/asciidoctor/blob/master/lib/asciidoctor/backends
: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
:idprefix:

{asciidoctor}[Asciidoctor] is a pure Ruby processor for converting
{asciidoc}[AsciiDoc] source files and strings into HTML 5, DocBook 4.5
and other formats.

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

Asciidoctor uses a set of built-in ERB templates to render the document
to HTML 5 or DocBook 4.5. We've matched the rendered output as close as
possible to the default 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 (read as 'tested') with Ruby 1.8.7, Ruby
1.9.3 and JRuby 1.7.2 (on Linux, Mac and Windows). We expect it will
work with other versions of Ruby as well and would welcome help in
testing it out.

The initial code from which Asciidoctor started emerged from the
{gitscm-next}[Git SCM site repo]. Refer to commit history of
{asciidoctor-seed}[asciidoc.rb] to view the initial contributions and
individual contributors.

The source code can now be found in the {asciidoctor-source}[Asciidoctor
source repository] on GitHub.

== Installation

NOTE: We are working hard to make Asciidoctor a drop-in replacement for
AsciiDoc. We're very close, with nearly 600 tests that ensure
compatibility. The march is on towards full compliance and beyond.

To install the gem:

 gem install asciidoctor

Or if you prefer bundler:

 bundle install asciidoctor

== Usage

Asciidoctor has both a command line interfac which can be used for 
everyday usage and an API for use in other projects. The command
is a drop in replacement for the `asciidoc` command of the python
implementation. The API, of course, is for integration with other
software projects and is suitable for server side applications such as
Rails, Sinatra and Github!

=== Command line

After asciidoctor has been installed the simplest invocation is:

 asciidoctor <asciidoc_file>

This will use the built-in defaults for options and create a new file
with the same base name, but with the .html extension in the same 
directory as the input file. There are many other options available 
and a full help is provided:

 asciidoctor --help

and also in the man page.

=== Asciidoctor API

To use Asciidoctor in your application, you first need to require the
library:

 require 'asciidoctor'

With that in place, you can start processing AsciiDoc documents.

.Loading a document
To parse a file into an `Asciidoctor::Document` object:

 doc = Asciidoctor.load_file('your_file.asciidoc')

You can get information about the document:

 puts doc.doctitle
 puts doc.attributes

More than likely, you want to just render the document.

.Rendering files
To render a file containing AsciiDoc markup to HTML 5:
{'fraction_non_alphanumeric': 0.09050262102991058, 'fraction_numerical': 0.00585877274128893, 'mean_word_length': 4.7713523131672595, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 18, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1302586', 'n_tokens_mistral': 2029, 'n_tokens_neox': 1993, 'n_words': 747}