anchor.diff:  . {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.
  +. 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.
  +. 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.
  
positive.code: 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')
  
  
negative.code:  puts Asciidoctor.render('*This* is it.', :header_footer => true,
     :template_dir => 'templates')
  
  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 (massive) test suite.
  
  == Differences from AsciiDoc
  
  While Asciidoctor aims to be compliant with the AsciiDoc syntax, there
  are some differences which are important to keep in mind. In some cases,
  it's to enforce a rule we believe is too lax or ambiguous in AsciiDoc.
  In other cases, it's a tradeoff for speed, smarter processing or a
  feature we just haven't yet implemented. (You'll also notice that
  Asciidoctor executes about 25x as fast as AsciiDoc).
  
  Here are the known cases where Asciidoctor differs from AsciiDoc:
  
  * Asciidoctor enables safe mode by default when using the API
    (+SafeMode::SECURE+)
  
  * Asciidoctor safe mode is even more safe than AsciiDoc's safe mode
  
  * Asciidoctor enforces symmetric block delimiters (the length of start
    and end delimiters for a block must match!)
  
  * Section title underlines must be within 1 character of the length of
    the title (AsciiDoc allows an offset of 3)
  
  * Asciidoctor's default HTML backend matches AsciiDoc's HTML 5 backend
    (whereas XHTML 1.1 is the default HTML backend in AsciiDoc)
  
  * Asciidoctor handles inline anchors more cleanly
  
  ** AsciiDoc adds an +<a>+ tag in the line and that markup gets caught in
     the generated id
  
  ** Asciidoctor promotes the id of the anchor as the section id
  
  * Asciidoctor strips XML entities from the section title before
    generating the id (makes for cleaner section ids)
  
  * Asciidoctor use +<tt>+ instead of +<span class="monospace">+ around
    inline literal text in the HTML backend
  
  * Asciidoctor is much more lenient about attribute list parsing (double
    quotes are rarely needed, though you may want to keep them for
    compatibility)
  
  * Asciidoctor creates xref labels using the text from the linked section
    title when rendering HTML to match how DocBook works
  
  * Asciidoctor allows commas to be used in xref labels, whereas AsciiDoc
    cuts off the label at the location of the first comma
  
  * Asciidoctor removes indentation for non-literal paragraphs in a list
    item
  +
  NOTE: In general, Asciidoctor handles whitespace much more intelligently
  +
  
  * In Asciidoctor, a horizontal ruler can have attributes
  
  * Asciidoctor skips over line comments in tables, whereas AsciiDoc doesn't
  
  * Asciidoctor uses its own API rather than a command line invocation to
    handle table cells that have AsciiDoc content
  
  * Asciidoctor supports resolving variables from parent document in table
    cells with AsciiDoc content
  
  * AsciiDoc doesn't carry over the doctype attribute passed from the
    commandline when rendering AsciiDoc content cells, whereas Asciidoctor does
  
  * Asciidoctor strips the file extension from the target image when
    generating alt text if no alt text is provided
  
  * Asciidoctor reifies the toc in the header of the document instead of
    relying on JavaScript to create it
  
  * Asciidoctor is nice about using a section title syntax inside a
    delimited block by simply ignoring it (AsciiDoc issues warnings)
  
  * Asciidoctor honors the alternate style name "discrete" for a floating
    title (i.e., +[discrete]+)
  
  * Asciidoctor supports syntax highlighting of listing or literal blocks
    that have the "source" style out of the box
  
  ** Asciidoctor honors the source-highlighter values +coderay+ and
     +highlightjs+, using CodeRay or highlight.js, respectively
  
  ** Asciidoctor does not currently support Pygments for source
     highlighting
  
  * Asciidoctor sets these additional intrinsic attributes
  
    +asciidoctor+::
      indicates Asciidoctor is being used; useful for conditional
      processing
  
    +asciidoctor-version+::
      indicates which version of Asciidoctor is in use
  
  * Asciidoctor does not support deprecated tables (you don't want them
    anyway)
  
  * Use can set the extension for icons using the +icontype+ attribute
    (AsciiDoc defaults to .png)
  
  * AsciiDoc uses the +<blockquote>+ and +<cite>+ tags in the HTML output
    for quote blocks, requiring some additional styling to match AsciiDoc
  +
   blockquote.content { padding: 0; margin; 0 }
   cite { color: navy; }
  +
  
  * Asciidoctor does not support the deprecated index term syntax (`++`
    and `+++`)
  
  * Asciidoctor does not yet ship w/ a stylesheet, must provide your own
    using the +stylesheet+ attribute
  
  * Asciidoctor introduces the +hardbreaks+ attribute, which inserts a
    line break character after each line of wrapped text
  
  * Asciidoctor introduces the +idseparator+ attribute to customize the
    separator used in generated section ids (AsciiDoc hardcodes +_+)
  
  * Asciidoctor does not support system evaluation macros
  
  * Asciidoctor does not support displaying comments
  
  * Asciidoctor properly calculates author initials if attribute reference
    is used in name
  
  * Asciidoctor allows the document id to be set using [[id]] above the
    document header (adds id attribute to +<body>+ tag)
  
  * Assigning value to the +listing-caption+ attribute will enable
    automatic captions for listings (like examples, tables and figures)
  
  * The +ifeval::[]+ macro is constrained for the strict purpose of
    comparing values of attributes
  
  If there's a difference you don't see in this list, check the {issues}[issue
  tracker] to see if it's an outstanding feature, or file an issue to report the
  difference.
  
  == Contributing
  
  In the spirit of {freesoftware}[free software], 'everyone' is encouraged to
  help improve this project.
  
  Here are some ways *you* can contribute:
  
  