asciidoctor 1.5.5 → 1.5.6

data/test/fixtures/asciidoc_index.txt

@@ -0,0 +1,521 @@
+AsciiDoc Home Page
+==================
+// Web page meta data.
+:keywords:    AsciiDoc, DocBook, EPUB, PDF, ebooks, slideshow, slidy, man page
+:description: AsciiDoc is a text document format for writing notes,  +
+              documentation, articles, books, ebooks, slideshows,    +
+              web pages, man pages and blogs.  AsciiDoc files can be +
+              translated to many formats including HTML, PDF, EPUB,  +
+              man page.
+
+
+.{revdate}: AsciiDoc {revnumber} Released
+************************************************************************
+Read the link:CHANGELOG.html[CHANGELOG] for release highlights and a
+full list of all additions, changes and bug fixes. Changes are
+documented in the updated link:userguide.html[User Guide]. See the
+link:INSTALL.html[Installation page] for downloads and and
+installation instructions.
+
+'Stuart Rackham'
+************************************************************************
+
+Introduction
+------------
+{description}
+
+AsciiDoc is highly configurable: both the AsciiDoc source file syntax
+and the backend output markups (which can be almost any type of
+SGML/XML markup) can be customized and extended by the user.
+
+AsciiDoc is free software and is licenced under the terms of the 'GNU
+General Public License version 2' (GPLv2).
+
+TIP: The pages you are reading were written using AsciiDoc, to view
+the corresponding AsciiDoc source click on the *Page Source* menu item
+in the left hand margin.
+
+
+Overview and Examples
+---------------------
+You write an AsciiDoc document the same way you would write a
+normal text document, there are no markup tags or weird format
+notations. AsciiDoc files are designed to be viewed, edited and
+printed directly or translated to other presentation formats using
+the asciidoc(1) command.
+
+The asciidoc(1) command translates AsciiDoc files to HTML, XHTML and
+DocBook markups.  DocBook can be post-processed to presentation
+formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript
+using readily available Open Source tools.
+
+Example Articles
+~~~~~~~~~~~~~~~~
+- This XHTML version of the
+  link:asciidoc.css-embedded.html[AsciiDoc User Guide]
+  was generated by AsciiDoc from
+  link:asciidoc.txt[this AsciiDoc file].
+
+- Here's the link:asciidoc.html[same document] created by first
+  generating DocBook markup using AsciiDoc and then converting the
+  DocBook markup to HTML using 'DocBook XSL Stylesheets'.
+
+- The User Guide again, this time a
+  link:chunked/index.html[chunked version].
+
+- AsciiDoc generated this link:article-standalone.html[stand-alone
+  HTML file] containing embedded CSS, JavaScript and images from this
+  link:article.txt[AsciiDoc article template] with this command:
+
+  asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
+
+- The same link:article.txt[AsciiDoc article template] generated
+  link:article-html5-toc2.html[this HTML 5] (the 'toc2' attribute puts
+  a table of contents in the left margin) from this command:
+
+  asciidoc -b html5 -a icons -a toc2 -a theme=flask article.txt
+
+- The same link:article.txt[AsciiDoc article template] produced
+  this link:article.html[HTML file] and this
+  link:article.pdf[PDF file] via DocBook markup generated by AsciiDoc.
+
+[[X7]]
+Example Books
+~~~~~~~~~~~~~
+AsciiDoc markup supports all the standard DocBook frontmatter and
+backmatter sections (dedication, preface, bibliography, glossary,
+index, colophon) plus footnotes and index entries.
+
+- This link:book.txt[AsciiDoc book] produced link:book.html[this HTML
+  file] using the 'DocBook XSL Stylesheets'.
+- The link:asciidoc.pdf[PDF formatted AsciiDoc User Guide] was
+  generated from asciidoc(1) DocBook output.
+- The link:asciidoc.epub[EPUB formatted AsciiDoc User Guide] was
+  generated using link:a2x.1.html[a2x].
+- This link:book.epub[EPUB formatted book skeleton] was generated
+  using link:a2x.1.html[a2x].
+- This link:book-multi.txt[multi-part AsciiDoc book] produced
+  link:book-multi.html[this HTML file] using the 'DocBook XSL
+  Stylesheets'.
+
+Example UNIX Man Pages
+~~~~~~~~~~~~~~~~~~~~~~
+HTML formatted AsciiDoc man pages
+link:asciidoc.1.css-embedded.html[with stylesheets] and
+link:asciidoc.1.html[without stylesheets] were generated by AsciiDoc
+from link:asciidoc.1.txt[this file].
+
+This link:asciidoc.1[roff formatted  man page] was generated from
+asciidoc(1) DocBook output using `xsltproc(1)` and DocBook XSL
+Stylesheets.
+
+[[X8]]
+Example Slideshows
+~~~~~~~~~~~~~~~~~~
+The http://www.w3.org/Talks/Tools/Slidy2/[Slidy] backend generates
+HTML slideshows that can be viewed in any web browser.  What's nice is
+that you can create completely self contained slideshows including
+embedded images.
+
+- Here is the link:slidy.html[slidy backend documentation] slideshow
+  and here is it's link:slidy.txt[AsciiDoc source].
+- An link:slidy-example.html[example slidy slideshow] and the
+  link:slidy-example.txt[AsciiDoc source].
+
+Example Web Site
+~~~~~~~~~~~~~~~~
+The link:README-website.html[AsciiDoc website] is included in the
+AsciiDoc distribution (in `./examples/website/`) as an example website
+built using AsciiDoc.  See `./examples/website/README-website.txt`.
+
+More examples
+~~~~~~~~~~~~~
+- See below: <<X6,'Documents written using AsciiDoc'>>.
+- Example link:newtables.html[Tables].
+
+
+eBook Publication
+-----------------
+The two most popular open eBook formats are
+http://en.wikipedia.org/wiki/EPUB[EPUB] and PDF.
+The AsciiDoc link:a2x.1.html[a2x] toolchain wrapper makes it easy to
+link:publishing-ebooks-with-asciidoc.html[publish EPUB and PDF eBooks
+with AsciiDoc]. See also <<X7,example books>> and
+link:epub-notes.html[AsciiDoc EPUB Notes]).
+
+
+Blogpost weblog client
+----------------------
+http://srackham.wordpress.com/blogpost-readme/[blogpost] is a
+command-line weblog client for publishing AsciiDoc documents to
+http://wordpress.org/[WordPress] blog hosts. It creates and updates
+weblog posts and pages directly from AsciiDoc source documents.
+
+
+Source code highlighter
+-----------------------
+AsciiDoc includes a link:source-highlight-filter.html[source code
+highlighter filter] that uses
+http://www.gnu.org/software/src-highlite/[GNU source-highlight] to
+highlight HTML outputs. You also have the option of using the
+http://pygments.org/[Pygments] highlighter.
+
+
+[[X3]]
+Mathematical Formulae
+---------------------
+You can include mathematical formulae in AsciiDoc XHTML documents using
+link:asciimathml.html[ASCIIMathML] or link:latexmathml.html[LaTeXMathML]
+notation.
+
+The link:latex-filter.html[AsciiDoc LaTeX filter] translates LaTeX
+source to an image that is automatically inserted into the AsciiDoc
+output documents.
+
+AsciiDoc also has 'latexmath' macros for DocBook outputs -- they are
+documented in link:latexmath.pdf[this PDF file] and can be used in
+AsciiDoc documents processed by `dblatex(1)`.
+
+
+Editor Support
+--------------
+- An AsciiDoc syntax highlighter for the Vim text editor is included in the
+  AsciiDoc distribution (see the 'Vim Syntax Highlighter' appendix in
+  the 'AsciiDoc User Guide' for details).
++
+.Syntax highlighter screenshot
+image::images/highlighter.png[height=400,caption="",link="images/highlighter.png"]
+
+- Dag Wieers has implemented an alternative Vim syntax file for
+  AsciiDoc which can be found here
+  http://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/.
+- David Avsajanishvili has written a source highlighter for AsciiDoc
+  files for http://projects.gnome.org/gtksourceview/[GtkSourceView]
+  (used by http://projects.gnome.org/gedit/[gedit] and a number of
+  other applications). The project is hosted here:
+  https://launchpad.net/asciidoc-gtk-highlight
+- AsciiDoc resources for the Emacs editor can be found on the
+  http://www.emacswiki.org/emacs/AsciiDoc[AsciiDoc  page] at the
+  http://www.emacswiki.org/emacs/EmacsWiki[Emacs Wiki].
+- Christian Zuckschwerdt has written a
+  https://github.com/zuckschwerdt/asciidoc.tmbundle[TextMate bundle]
+  for AsciiDoc.
+
+
+Try AsciiDoc on the Web
+-----------------------
+Andrew Koster has written a Web based application to interactively
+convert and display AsciiDoc source:
+http://andrewk.webfactional.com/asciidoc.php
+
+
+[[X2]]
+External Resources and Applications
+-----------------------------------
+Here are resources that I know of, if you know of more drop me a line
+and I'll add them to the list.
+
+- Check the link:INSTALL.html#X2[installation page] for packaged versions
+  of AsciiDoc.
+- Alex Efros has written an HTML formatted
+  http://powerman.name/doc/asciidoc[AsciiDoc Cheatsheet] using
+  Asciidoc.
+- Thomas Berker has written an
+  http://liksom.info/blog/?q=node/114[AsciiDoc Cheatsheet] in Open
+  Document and PDF formats.
+- The http://www.wikimatrix.org/[WikiMatrix] website has an excellent
+  http://www.wikimatrix.org/syntax.php[web page] that compares the
+  various Wiki markup syntaxes. An interesting attempt at Wiki markup
+  standardization is http://www.wikicreole.org/[CREOLE].
+- Franck Pommereau has written
+  http://www.univ-paris12.fr/lacl/pommereau/soft/asciidoctest.html[Asciidoctest],
+  a program that doctests snippets of Python code within your Asciidoc
+  documents.
+- The http://remips.sourceforge.net/[ReMIPS] project website has been
+  built using AsciiDoc.
+- Here are some link:asciidoc-docbook-xsl.html[DocBook XSL Stylesheets
+  Notes].
+- Karl Mowatt-Wilson has developed an http://ikiwiki.info/[ikiwiki]
+  plugin for AsciiDoc which he uses to render
+  http://mowson.org/karl[his website].  The plugin is available
+  http://www.mowson.org/karl/colophon/[here] and there is some
+  discussion of the ikiwiki integration
+  http://ikiwiki.info/users/KarlMW/discussion/[here].
+- Glenn Eychaner has
+  http://groups.google.com/group/asciidoc/browse_thread/thread/bf04b55628efe214[reworked
+  the Asciidoc plugin for ikiwiki] that was created by Karl Mowson,
+  the source can be downloaded from
+  http://dl.dropbox.com/u/11256359/asciidoc.pm
+- David Hajage has written an AsciiDoc package for the
+  http://www.r-project.org/[R Project] (R is a free software
+  environment for statistical computing).  'ascii' is available on
+  'CRAN' (just run `install.packages("ascii")` from R).  Briefly,
+  'ascii' replaces R results in AsciiDoc document with AsciiDoc
+  markup.  More information and examples here:
+  http://eusebe.github.com/ascii/.
+- Pascal Rapaz has written a Python script to automate AsciiDoc
+  website generation. You can find it at
+  http://www.rapazp.ch/opensource/tools/asciidoc.html.
+- Jared Henley has written
+  http://jared.henley.id.au/software/awb/documentation.html[AsciiDoc
+  Website Builder]. 'AsciiDoc Website Builder' (awb) is a python
+  program that automates the building of of a website written in
+  AsciiDoc. All you need to write is the AsciiDoc source plus a few
+  simple configuration files.
+- Brad Adkins has written
+  http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen], a
+  web site generation and deployment tool that allows you write your
+  web site content in AsciiDoc. The
+  http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen web
+  site] is managed using 'AsciiDocGen'.
+- Filippo Negroni has developed a set of tools to facilitate 'literate
+  programming' using AsciiDoc.  The set of tools is called
+  http://eweb.sourceforge.net/[eWEB].
+- http://vanderwijk.info/2009/4/23/full-text-based-document-generation-using-asciidoc-and-ditaa[Ivo's
+  blog] describes a http://ditaa.sourceforge.net/[ditaa] filter for
+  AsciiDoc which converts http://en.wikipedia.org/wiki/ASCII_art[ASCII
+  art] into graphics.
+- http://github.com/github/gollum[Gollum] is a git-powered wiki, it
+  supports various formats, including AsciiDoc.
+- Gregory Romé has written an
+  http://github.com/gpr/redmine_asciidoc_formatter[AsciiDoc plugin]
+  for the http://www.redmine.org/[Redmine] project management
+  application.
+- Paul Hsu has started a
+  http://github.com/paulhsu/AsciiDoc.CHT.userguide[Chinese translation
+  of the AsciiDoc User Guide].
+- Dag Wieers has written
+  http://dag.wieers.com/home-made/unoconv/[UNOCONV]. 'UNOCONV' can
+  export AsciiDoc outputs to OpenOffice export formats.
+- Ed Keith has written http://codeextactor.berlios.de/[Code
+  Extractor], it extracts code snippets from source code files and
+  inserts them into AsciiDoc documents.
+- The http://csrp.iut-blagnac.fr/jmiwebsite/home/[JMI website] hosts
+  a number of extras for AsciiDoc and Slidy written by Jean-Michel
+  Inglebert.
+- Ryan Tomayko has written an number of
+  http://tomayko.com/src/adoc-themes/[themes for AsciiDoc] along with
+  a http://tomayko.com/src/adoc-themes/hacking.html[script for
+  combining the CSS files] into single CSS theme files for AsciiDoc
+  embedded CSS documents.
+- Ilya Portnov has written a
+  https://gitorious.org/doc-building-system[document building system
+  for AsciiDoc], here is
+  http://iportnov.blogspot.com/2011/03/asciidoc-beamer.html[short
+  article in Russian] describing it.
+- Lex Trotman has written
+  https://github.com/elextr/codiicsa[codiicsa], a program that
+  converts DocBook to AsciiDoc.
+- Qingping Hou has written http://houqp.github.com/asciidoc-deckjs/[an
+  AsciiDoc backend for deck.js].
+  http://imakewebthings.github.com/deck.js/[deck.js] is a JavaScript
+  library for building modern HTML presentations (slideshows).
+- The guys from O'Reilly Media have posted an
+  https://github.com/oreillymedia/docbook2asciidoc[XSL Stylesheet to
+github] that converts DocBook to AsciiDoc.
+- Lex Trotman has written
+  https://github.com/elextr/flexndex[flexndex], an index generator
+  tool that be used with AsciiDoc.
+- Michael Haberler has created a
+  https://code.google.com/p/asciidoc-diag-filter/[blockdiag filter for
+  Asciidoc] which embeds http://blockdiag.com/[blockdiag] images in
+  AsciiDoc documents.
+- Dan Allen has written a
+  https://github.com/mojavelinux/asciidoc-bootstrap-docs-backend[Bootstrap
+  backend] for AsciiDoc.
+- Steven Boscarine has written
+  https://github.com/StevenBoscarine/JavaAsciidocWrapper[Maven wrapper for AsciiDoc].
+- Christian Goltz has written
+  https://github.com/christiangoltz/shaape[Shaape], an Ascii art to
+  image converter for AsciiDoc.
+- Eduardo Santana has written an
+  https://github.com/edusantana/asciidoc-highlight[Asciidoc Highlight
+  for Notepad++].
+- http://www.geany.org/[Geany] 1.23 adds document structure support
+  for AsciiDoc.
+
+Please let me know if any of these links need updating.
+
+
+[[X6]]
+Documents written using AsciiDoc
+--------------------------------
+Here are some documents I know of, if you know of more drop me a line
+and I'll add them to the list.
+
+- The book http://practicalunittesting.com/[Practical Unit Testing] by
+  Tomek Kaczanowski was
+  https://groups.google.com/group/asciidoc/browse_frm/thread/4ba13926262efa23[written
+  using Asciidoc].
+
+- The book http://oreilly.com/catalog/9781449397296[Programming iOS 4]
+  by Matt Neuburg was written using AsciiDoc. Matt has
+  http://www.apeth.net/matt/iosbooktoolchain.html[written an article]
+  describing how he used AsciiDoc and other tools to write the book.
+
+- The book
+  http://oreilly.com/catalog/9780596155957/index.html[Programming
+  Scala] by Dean Wampler and Alex Payne (O'Reilly) was
+  http://groups.google.com/group/asciidoc/browse_frm/thread/449f1199343f0e27[written
+  using Asciidoc].
+
+- The http://www.ncfaculty.net/dogle/fishR/index.html[fishR] website
+  has a number of
+  http://www.ncfaculty.net/dogle/fishR/bookex/AIFFD/AIFFD.html[book
+  examples] written using AsciiDoc.
+
+- The Neo4j graph database project uses Asciidoc, and the output is
+  published here: http://docs.neo4j.org/. The build process includes
+  live tested source code snippets and is described
+  http://groups.google.com/group/asciidoc/browse_thread/thread/49d570062fd3ff52[here].
+
+- http://frugalware.org/[Frugalware Linux] uses AsciiDoc for
+  http://frugalware.org/docs[documentation].
+- http://www.cherokee-project.com/doc/[Cherokee documentation].
+
+- Henrik Maier produced this professional User manual using AsciiDoc:
+  http://www.proconx.com/assets/files/products/modg100/UMMBRG300-1101.pdf
+
+- Henrik also produced this folded single page brochure format
+  example:
+  http://www.proconx.com/assets/files/products/modg100/IGMBRG300-1101-up.pdf
++
+See this
+http://groups.google.com/group/asciidoc/browse_thread/thread/16ab5a06864b934f[AsciiDoc
+discussion group thread] for details.
+
+- The
+  http://www.kernel.org/pub/software/scm/git/docs/user-manual.html[Git
+  User's Manual].
+- 'Git Magic' +
+  http://www-cs-students.stanford.edu/~blynn/gitmagic/ +
+  http://github.com/blynn/gitmagic/tree/1e5780f658962f8f9b01638059b27275cfda095c
+- 'CouchDB: The Definitive Guide' +
+  http://books.couchdb.org/relax/ +
+  http://groups.google.com/group/asciidoc/browse_thread/thread/a60f67cbbaf862aa/d214bf7fa2d538c4?lnk=gst&q=book#d214bf7fa2d538c4
+- 'Ramaze Manual' +
+  http://book.ramaze.net/ +
+  http://github.com/manveru/ramaze-book/tree/master
+- Some documentation about git by Nico Schottelius (in German)
+  http://nico.schotteli.us/papers/linux/git-firmen/.
+- The http://www.netpromi.com/kirbybase_ruby.html[KirbyBase for Ruby]
+  database management system manual.
+- The http://xpt.sourceforge.net/[*Nix Power Tools project] uses
+  AsciiDoc for documentation.
+- The http://www.wesnoth.org/[Battle for Wesnoth] project uses
+  AsciiDoc for its http://www.wesnoth.org/wiki/WesnothManual[Manual]
+  in a number of different languages.
+- Troy Hanson uses AsciiDoc to generate user guides for the
+  http://tpl.sourceforge.net/[tpl] and
+  http://uthash.sourceforge.net/[uthash] projects (the HTML versions
+  have a customised contents sidebar).
+- http://volnitsky.com/[Leonid Volnitsky's site] is generated using
+  AsciiDoc and includes Leonid's matplotlib filter.
+- http://www.weechat.org/[WeeChat] uses AsciiDoc for
+  http://www.weechat.org/doc[project documentation].
+- http://www.clansuite.com/[Clansuite] uses AsciiDoc for
+  http://www.clansuite.com/documentation/[project documentation].
+- The http://fc-solve.berlios.de/[Freecell Solver program] uses
+  AsciiDoc for its
+  http://fc-solve.berlios.de/docs/#distributed-docs[distributed
+  documentation].
+- Eric Raymond's http://gpsd.berlios.de/AIVDM.html[AIVDM/AIVDO
+  protocol decoding] documentation is written using AsciiDoc.
+- Dwight Schauer has written an http://lxc.teegra.net/[LXC HOWTO] in
+  AsciiDoc.
+- The http://www.rowetel.com/ucasterisk/[Free Telephony Project]
+  website is generated using AsciiDoc.
+- Warren Block has http://www.wonkity.com/~wblock/docs/[posted a
+  number of articles written using AsciiDoc].
+- The http://code.google.com/p/waf/[Waf project's] 'Waf Book' is
+  written using AsciiDoc, there is an
+  http://waf.googlecode.com/svn/docs/wafbook/single.html[HTML] and a
+  http://waf.googlecode.com/svn/docs/wafbook/waf.pdf[PDF] version.
+- The http://www.diffkit.org/[DiffKit] project's documentation and
+  website have been written using Asciidoc.
+- The http://www.networkupstools.org[Network UPS Tools] project
+  http://www.networkupstools.org/documentation.html[documentation] is
+  an example of a large documentation project written using AsciiDoc.
+- http://www.archlinux.org/pacman/[Pacman], the
+  http://www.archlinux.org/[Arch Linux] package manager, has been
+  documented using AsciiDoc.
+- Suraj Kurapati has written a number of customized manuals for his
+  Open Source projects using AsciiDoc:
+
+  * http://snk.tuxfamily.org/lib/detest/
+  * http://snk.tuxfamily.org/lib/ember/
+  * http://snk.tuxfamily.org/lib/inochi/
+  * http://snk.tuxfamily.org/lib/rumai/
+
+- The http://cxxtest.com/[CxxTest] project (unit testing for C++
+  language) has written its User Guide using AsciiDoc.
+
+Please let me know if any of these links need updating.
+
+
+DocBook 5.0 Backend
+-------------------
+Shlomi Fish has begun work on a DocBook 5.0 `docbook50.conf` backend
+configuration file, you can find it
+http://bitbucket.org/shlomif/asciidoc[here]. See also:
+http://groups.google.com/group/asciidoc/browse_thread/thread/4386c7cc053d51a9
+
+
+[[X1]]
+LaTeX Backend
+-------------
+An experimental LaTeX backend was written for AsciiDoc in 2006 by
+Benjamin Klum.  Benjamin did a superhuman job (I admit it, I didn't
+think this was doable due to AsciiDoc's SGML/XML bias).  Owning to to
+other commitments, Benjamin was unable to maintain this backend.
+Here's link:latex-backend.html[Benjamin's original documentation].
+Incompatibilities introduced after AsciiDoc 8.2.7 broke the LaTeX
+backend.
+
+In 2009 Geoff Eddy stepped up and updated the LaTeX backend, thanks to
+Geoff's efforts it now works with AsciiDoc 8.4.3. Geoff's updated
+`latex.conf` file shipped with AsciiDoc version 8.4.4. The backend
+still has limitations and remains experimental (see
+link:latex-bugs.html[Geoff's notes]).
+
+It's probably also worth pointing out that LaTeX output can be
+generated by passing AsciiDoc generated DocBook through `dblatex(1)`.
+
+
+Patches and bug reports
+-----------------------
+Patches and bug reports are are encouraged, but please try to follow
+these guidelines:
+
+- Post bug reports and patches to the
+  http://groups.google.com/group/asciidoc[asciidoc discussion list],
+  this keeps things transparent and gives everyone a chance to
+  comment.
+- The email subject line should be a specific and concise topic
+  summary. Commonly accepted subject line prefixes such as '[ANN]',
+  '[PATCH]' and '[SOLVED]' are good.
+
+=== Bug reports
+- When reporting problems please illustrate the problem with the
+  smallest possible example that replicates the issue (and please test
+  your example before posting). This technique will also help to
+  eliminate red herrings prior to posting.
+- Paste the commands that you executed along with any relevant
+  outputs.
+- Include the version of AsciiDoc and the platform you're running it
+  on.
+- If you can program please consider writing a patch to fix the
+  problem.
+
+=== Patches
+- Keep patches small and atomic (one issue per patch) -- no patch
+  bombs.
+- If possible test your patch against the current trunk.
+- If your patch adds or modifies functionality include a short example
+  that illustrates the changes.
+- Send patches in `diff -u` format, inline inside the mail message is
+  usually best; if it is a very long patch then send it as an
+  attachment.
+- Include documentation updates if you're up to it; otherwise insert
+  'TODO' comments at relevant places in the documentation.
+