anchor.diff:  :awestruct-layout: base
   :homepage: http://asciidoctor.org
   :asciidoc: http://asciidoc.org
  +:gem: http://rubygems.org/gems/asciidoctor
  +:toolchain: http://asciidoctor.org/docs/install-toolchain/
  +:install-mac: http://asciidoctor.org/docs/install-asciidoctor-macosx/
  +:render: http://asciidoctor.org/docs/render-documents
  +:factory: http://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory
  +:man: http://asciidoctor.org/man/asciidoctor 
   :sources: https://github.com/asciidoctor/asciidoctor
   :issues: https://github.com/asciidoctor/asciidoctor/issues
   :forum: http://discuss.asciidoctor.org
  +:irc: irc://irc.freenode.org/#asciidoctor
  +:news: http://asciidoctor.org/news/
  +:docs: http://asciidoctor.org/docs/
   :org: https://github.com/asciidoctor
   :contributors: https://github.com/asciidoctor/asciidoctor/graphs/contributors
   :templates: https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/backends
  
positive.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].
  
negative.code: :idprefix:
  :idseparator: -
  
  {homepage}[Asciidoctor] is a pure Ruby processor for converting {asciidoc}[AsciiDoc] source files and strings into HTML 5, DocBook 5.0, DocBook 4.5 and other formats. 
  It's {gem}[published as a RubyGem] and is available under the MIT open source license.
  
  ifndef::awestruct[]
  image::https://travis-ci.org/asciidoctor/asciidoctor.png?branch=master[Build Status, link="https://travis-ci.org/asciidoctor/asciidoctor"]
  endif::awestruct[]
  
  Asciidoctor uses a set of built-in ERB templates to render the document to HTML 5 or DocBook.
  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 <<usage>> section for more details.
  
  == Operating Systems
  
  Asciidoctor works on Linux, Mac and Windows.
  
  == Dependency and Configuration Requirements
  
  Asciidoctor requires one of the following implementations of Ruby:
  
  * Ruby 1.8.7
  * Ruby 1.9.3
  * Ruby 2.0.0
  * JRuby 1.7.4
  * Rubinius 1.2.4 or nightly
  
  We expect it will work with other versions of Ruby as well and would welcome help testing them.
  
  // What is considered configuration information?
  
  // What about other sub-projects of Asciidoctor that require Tilt?
  
  ////
  == List of files/directory structure
  
  Optional depending on the complexity of the project
  ////
  
  The latest source code is located in the {sources}[Asciidoctor source repository] on GitHub.
  
  == Installation
  
  // Update the test number
  
  NOTE: We're working hard to make Asciidoctor a drop-in replacement for AsciiDoc. 
  We're very close, with over 700 tests that ensure compatibility. 
  The march is on towards full compliance and beyond.
  
  Asciidoctor can be installed via the +gem+ command, bundler, or the +yum+ package manager.
  
  To install Asciidoctor:
  
  . Open a terminal
  . Type the +gem+ command
  
   $> gem install asciidoctor
  
  To install Asciidoctor using bundler:
  
  . Open your system Gemfile
  . Add the +asciidoctor+ gem to your Gemfile using the following text
  
   source 'https://rubygems.org'
   gem 'asciidoctor'
  
  . Save the Gemfile
  . Open a terminal
  . Install the gem with bundler
  
   $> bundle install
   
  To install Asciidoctor on Fedora 17 or greater:
  
  . Open a terminal
  . Type the +yum+ command
   
   $> sudo yum install rubygem-asciidoctor
  
  The benefit of installing the gem via +yum+ is that the package manager will also install Ruby if it's not already on your machine.
  
  Additional documentation:
  
  * {toolchain}[Installing the Asciidoctor toolchain]
  * {install-mac}[Installing Asciidoctor on Mac OS X]
  
  == Upgrade
  
  If you have an earlier version of Asciidoctor installed, you can update it using the +gem+ command:
  
   $> gem update asciidoctor
  
  [TIP]
  ====
  If you accidentally use +gem install+ instead of +gem update+ then you will have both versions installed.
  If you wish to remove the older version use the +gem+ command:
  
   $> gem cleanup asciidoctor
  ====
  
  On Fedora, you can update it using:
  
   $> sudo yum update rubygem-asciidoctor
  
  TIP: Your Fedora system may be configured to automatically update packages, in which case no further action is required by you.
  Refer to the http://docs.fedoraproject.org[Fedora docs] if you are unsure.
  
  NOTE: The +yum+ package update will not be available at the same time as the +gem+, it may take several weeks before it becomes available.
  If you must have the latest version now, then use the +gem+ method instead.
  
  == Usage
  
  If the +asciidoctor+ gem installed successfully, the +asciidoctor+ command line interface (CLI) will be available on your PATH.
  To invoke it, execute:
  
   $> asciidoctor --version
   Asciidoctor 0.1.4 [http://asciidoctor.org]
  
  In addition to the CLI, Asciidoctor provides an API.
  The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.
  
  === Command line interface (CLI)
  
  Asciidoctor's CLI is a drop-in replacement for the +asciidoc.py+ command from the Python implementation. 
  To invoke Asciidoctor from the CLI, execute:
  
   asciidoctor <asciidoc_file>
  
  This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base name, but with the +.html+ extension.
  
  There are many other options available and full help is provided via:
  
   asciidoctor --help
  
  or in the {man}[man page].
  
  There is also an +asciidoctor-safe+ command, which turns on safe mode by default, preventing access to files outside the parent directory of the source file. 
  This mode is very similar to the safe mode of +asciidoc.py+.
  
  Additional documentation:
  
  * {render}[How do I render a document?]
  * {factory}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]
  
  === Ruby API
  
  To use Asciidoctor in your application, you first need to require the gem:
  
   require 'asciidoctor'
  
  