asciidoctor 0.1.1 → 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c8a3cff3d36fc7c331d8fa58ec52d3de55c82a01
+  data.tar.gz: 4096f0425da556b1c4fb0c808fcf09f2c3848131
+SHA512:
+  metadata.gz: 57e7391640b1677fb9d19ecde95af02a6cd53111613d0335e0618901a55dff080aa1bab1290a2f0d591de7ec5db7a8c9e198ba78b386d7c1a3f3b0a3ba5953f6
+  data.tar.gz: 6f6f8002274a90e950327b5ecd69d3a05d760f842acc9b70fdce6c17a55e039dcd1c293d06b565047b7c7557c128f375e6ba7d8f37c4e28318207fe6bc002a03

data/Gemfile

@@ -1,2 +1,2 @@
-source :rubygems
+source 'https://rubygems.org'
 gemspec

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) Ryan Waldron
+Copyright (c) Ryan Waldron and Dan Allen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.

data/README.adoc

@@ -0,0 +1,461 @@
+= Asciidoctor
+:homepage: http://asciidoctor.org
+:asciidoc: http://asciidoc.org
+:sources: http://github.com/asciidoctor/asciidoctor
+:issues: https://github.com/asciidoctor/asciidoctor/issues
+:forum: http://discuss.asciidoctor.org
+:org: http://github.com/asciidoctor
+:contributors: https://github.com/asciidoctor/asciidoctor/graphs/contributors
+:templates: https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/backends
+:gitscm-next: https://github.com/github/gitscm-next
+:seed-contribution: https://github.com/github/gitscm-next/commits/master/lib/asciidoc.rb
+:tilt: https://github.com/rtomayko/tilt
+:freesoftware: http://www.fsf.org/licensing/essays/free-sw.html
+: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/asciidoctor/asciidoctor/blob/master/LICENSE
+:idprefix:
+:idseparator: -
+
+{homepage}[Asciidoctor] is a pure Ruby processor for converting
+{asciidoc}[AsciiDoc] source files and strings into HTML 5, DocBook 4.5
+and other formats. It's http://rubygems.org/gems/asciidoctor[published
+as a RubyGem] and is available under the MIT open source license.
+
+image::https://travis-ci.org/asciidoctor/asciidoctor.png?branch=master[Build Status, link="https://travis-ci.org/asciidoctor/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 <<usage,Usage>> for more details.
+
+Asciidoctor currently works (read as 'tested') with Ruby 1.8.7, Ruby
+1.9.3, Ruby 2.0.0, JRuby 1.7.2 and Rubinius 1.2.4 (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
+{seed-contribution}[asciidoc.rb] to view the initial contributions and
+individual contributors.
+
+The source code can now be found in the {sources}[Asciidoctor source
+repository] on GitHub.
+
+== Installation
+
+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.
+
+To install the gem:
+
+ gem install asciidoctor
+
+Or if you prefer bundler, add the asciidoctor gem to your Gemfile,
+
+ source 'https://rubygems.org'
+ gem 'asciidoctor'
+
+then install it using bundler:
+
+ bundle install
+
+If you're running Fedora, you can install the gem using yum:
+
+ sudo yum install rubygem-asciidoctor
+
+The benefit of installing the gem via yum is that yum will also install
+Ruby if it's not already on your machine.
+
+== Usage
+
+Asciidoctor has both a command line interface (CLI) and an API. The CLI
+is a drop-in replacement for the +asciidoc.py+ command from the python
+implementation. 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)
+
+After installing the +asciidoctor+ gem, the +asciidoctor+ commandline
+interface should be available on your PATH. To invoke it, simply 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 http://asciidoctor.org/man/asciidoctor[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+.
+
+=== Ruby API
+
+To use Asciidoctor in your application, you first need to require the
+gem:
+
+ 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:
+
+ Asciidoctor.render_file('your_file.asciidoc', :in_place => true)
+
+The command will output to the file +your_file.html+ in the same
+directory. You can render the file to DocBook 4.5 by setting the
++backend+ attribute to 'docbook':
+
+ Asciidoctor.render_file('your_file.asciidoc', :in_place => true,
+   :attributes => {'backend' => 'docbook'})
+
+The command will output to the file +your_file.xml+ in the same
+directory. (If you're on Linux, you can view the file using yelp).
+
+.Rendering strings
+To render an AsciiDoc-formatted string:
+
+ puts Asciidoctor.render('*This* is it.')
+
+When rendering a string, the header and footer are excluded by default
+to make Asciidoctor consistent with other lightweight markup engines
+like Markdown. If you want the header and footer, just enable it using
+the +:header_footer+ option:
+
+ puts Asciidoctor.render('*This* is it.', :header_footer => true)
+
+Now you'll get a full HTML 5 file. As before, you can also produce
+DocBook 4.5:
+
+ puts Asciidoctor.render('*This* is it.', :header_footer => true,
+   :attributes => {'backend' => 'docbook'})
+
+If you don't like the output you see, you can change it. Any of it!
+
+.Custom templates
+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.
+
+ 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 adds viewport meta tag to +<head>+ to optimize mobile viewing
+
+* 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 uses +<code>+ instead of +<span class="monospace">+ around
+  inline literal text in the HTML backend
+
+* Asciidoctor does not wrap email next to author name in header in
+  angle brackets
+
+* Asciidoctor allows email field to be a URL and renders it as such
+
+* Asciidoctor is much more lenient about attribute list parsing (double
+  quotes are rarely needed, though you may want to keep them for
+  compatibility)
+
+* Asciidoctor recognizes +opts+ as an alias for the +options+ attribute.
+
+* 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 wraps +<col>+ elements in +<colgroup>+ in tables
+
+* Asciidoctor uses +<code>+ around content in monospaced table cells
+
+* 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 table cells, whereas Asciidoctor does
+
+* Asciidoctor does not require commas between attributes with quoted
+  values in a block attribute list
+
+* 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 sets CSS class on toc element, read from the +toc-class+
+  attribute; defaults to toc attribute name (+toc+ or +toc2+).
+
+* Asciidoctor honors the id, title, role and levels attributes set on
+  the toc macro.
+
+* Asciidoctor does not output two tocs with the same id.
+
+* 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>+ for the content and +<cite>+ tag for
+  attribution title 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 author and revision attributes to be referenced
+  in subsequent attribute entries in header (unlike AsciiDoc)
+
+* Asciidoctor allows multiple authors to be defined, separated by
+  semicolon. In DocBook backend, the authors are listed in an
+  +<authorgroup>+ element.
+
+* 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
+
+* The +include::[]+ macro is converted to a link to the target document
+  when SafeMode is SECURE or greater (this makes for a friendly
+  experience on GitHub)
+
+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:
+
+* 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
+** write tests!
+* 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
+* Ruby 2.0.0
+* JRuby 1.7.2
+* Rubinius 1.2.4
+
+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.
+
+== Resources
+
+Project home page:: {homepage}
+
+Source repository:: {sources}
+
+Issue tracker:: {issues}
+
+Mailinglist / forum:: {forum}
+
+GitHub organization:: {org}
+
+== Authors
+
+*Asciidoctor* was written by Ryan Waldron, Dan Allen and
+{contributors}[other contributors].
+
+*AsciiDoc* was written by Stuart Rackham and has received contributions
+from many other individuals.
+
+== Copyright
+
+Copyright (C) 2012-2013 Ryan Waldron and Dan Allen. See {license}[LICENSE] for details.
+
+// vim: tw=72