AsciiDoc Home Page ================== .{revdate}: AsciiDoc {revnumber} Released ************************************************************************ This release contains a few improvements, a couple of bug fixes and documentation updates. Read the link:CHANGELOG.html[CHANGELOG] for 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. mailto:srackham@gmail.com['Stuart Rackham'] ************************************************************************ Introduction ------------ AsciiDoc is a text document format for writing short documents, articles, books and UNIX man pages. AsciiDoc files can be translated to HTML and DocBook markups using the asciidoc(1) command. 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. 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 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] produced this link:article.html[HTML file] and this link:article.pdf[PDF file] via DocBook markup generated by AsciiDoc. - This link:asciidoc.pdf[PDF formatted User Guide] was generated from asciidoc(1) DocBook output. - This link:article.epub[EPUB formatted article] was generated using link:a2x.1.html[a2x]. Example Books ~~~~~~~~~~~~~ AsciiDoc markup supports all the standard DocBook frontmatter and backmatter sections (dedication, preface, bibliography, glossary, index, colophon) plus footnotes and index entries. Book:: This link:book.txt[AsciiDoc book's] DocBook output produced link:book.html[this HTML file] using the 'DocBook XSL Stylesheets'. Multi-part book:: This link:book-multi.txt[multi-part AsciiDoc book's] DocBook output 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. Example Web Site ~~~~~~~~~~~~~~~~ The link:README-website.html[AsciiDoc website] is included in the AsciiDoc distribution (in `./examples/website/`) as example website built using AsciiDoc. See `./examples/website/README-website.txt`. More examples ~~~~~~~~~~~~~ - See below: <>. - Example link:newtables.html[Tables]. Music Filter ------------ A link:music-filter.html[music filter] is included in the distribution `./filters/` directory. It translates music in http://lilypond.org/[LilyPond] or http://abcnotation.org.uk/[ABC] notation to standard classical notation Source Code Highlight Filter ---------------------------- A link:source-highlight-filter.html[source code highlight filter] is included in the distribution `./filters/` directory. [[X4]] Graphviz Filter --------------- Gouichi Iisaka has written a http://www.graphviz.org/[Graphviz] filter for AsciiDoc. Graphviz generates diagrams from a textual specification. Gouichi Iisaka's Graphviz filter is included in the AsciiDoc distribution. Here are some link:asciidoc-graphviz-sample.html[AsciiDoc Graphviz examples]. [[X3]] Mathematical Formulae --------------------- You can include mathematical formulae in AsciiDoc XHTML documents using link:asciimathml.html[ASCIIMathML] or link:latexmathml.html[LaTeXMathML] notation. link:latexmath.pdf[LaTeX Math] can be included in AsciiDoc documents processed by `dblatex(1)`. Vim Syntax Highlighter ---------------------- An AsciiDoc syntax highlighter for the Vim text editor is included in the AsciiDoc distribution (see 'Appendix F' of the 'AsciiDoc User Guide' for details). .Syntax highlighter screenshot image::images/highlighter.png[height=250,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/. [[X5]] matplotlib Filter ----------------- Leonid Volnitsky has written a http://volnitsky.com/project/mplw/index.html[matplotlib] filter for AsciiDoc. Using this filter you can generate charts from inline matplotlib scripts. 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]] Resources --------- Here are resources that I know of, if you know of more drop me a line and I'll add them to the list. - 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 - 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]. - Terrence Brannon has written http://github.com/metaperl/asciidoc-el[AsciiDoc functions for Emacs]. - Florian Kaufman has written http://code.google.com/p/sensorflo-emacs/source/browse/trunk/adoc-mode.el[adoc-mode.el] -- a major-mode for editing asciidoc files in Emacs. - Sun Tong has written an http://xpt.sourceforge.net/tools/doc-mode/[Emacs mode for AsciiDoc fontlocking]. - The http://xpt.sourceforge.net/[*Nix Power Tools project] has released an http://xpt.sourceforge.net/tools/doc-mode/[AsciiDoc syntax highlighter for Emacs]. - 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]. - 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.package("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]. Please let me know if any of these links need updating. 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. [[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://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. - 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/gcpmg/UMGCPMG-0801.pdf. - Henrik also produced this folded single page brochure format example: http://www.proconx.com/gcpmg/IGGCPMG-0801-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 and has released an Emacs syntax highlighter (see <> above). - 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 <>. - 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. Please let me know if any of these links need updating. [[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)`.