Shared publicly  - 
 
Wow! AsciiDoc is incredible!! I'm impressed!

I now consider myself well-versed in AsciiDoc after spending two days converting several full-length technical tutorials to AsciiDoc and really digging deep into its capabilities.

AsciiDoc is a lightweight, yet powerful markup language that's got it all:

- It's readable
- It's comprehensive
- It's extensible
- It produces beautiful output (in HTML, DocBook, PDF, ePub and more)

Now this is a lightweight markup language worthy of producing a book!

Tip: If you are interested in using it to write a book, see git-scribe: https://github.com/schacon/git-scribe

Think of it this way:

If Markdown is a 1st-grader, then AsciiDoc is PhD student.

For basic formatting, Markdown and AsciiDoc look remarkably similar, making AsciiDoc a drop-in, no-brainer replacement to Markdown (both in terms of simplicity and straightforward migration). Yet, the AsciiDoc syntax seems to continue on with no end. In fact, there is no end since it can be extended (and tweaked) rather easily.

What about Docbook? Ah! The great thing about AsciiDoc is that you can still produce Docbook without any of the pain or without sacrificing any features. Perhaps AsciiDoc should adopt this slogan:

Writing in Docbook is just, inhumane.

I could list all features AsciiDoc supports, but a showcase speaks for itself: http://powerman.name/doc/asciidoc

Getting back to my experiment....

I had the opportunity to seriously evaluate and contrast the serious lightweight markup languages: reStructuredText (and its complement Sphinx), Textile and AsciiDoc. Hands down, AsciiDoc is the winner. If there's such a thing as a sure thing in software, AsciiDoc is it.

I first converted a full-length technical tutorial into reStructuredText. It took roughly 3 hours to struggle through the syntax and get it converted, with holes still remaining here and there. The syntax is just quirky (what's the obsession with backticks and colons?) and hard to commit to memory. On the whole, it just leaves a bad taste. I was pretty deflated and ready to throw in the towel.

On my way to bed, a hint of curiosity motivated me to give AsciiDoc a shot. Within 15 minutes I had converted the whole document. Plus, I had outputs in HTML, PDF, plain text, ePub and Docbook to show for it. I was even starting to play with additional formatting and organization features. I felt like I found the holy grail of documentation.

Here's the result of that experiment:

Source
http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.asciidoc

Conf
http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.conf

HTML
http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.html

PDF
http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.pdf

Documentation can be easy and fun. Who would have thought?

I'm about as excited about AsciiDoc as I am about git (and the combination is just bliss). And there's still so much to explore. I definitely encourage you to check it out. AsciiDoc is even supported as a markup format on github (and gists), making it easy to get started.

Tip: If you're on Fedora, download the latest version of AsciiDoc from the website rather than install the RPM. The RPM is missing files from the distribution.
45
24
Samir Faci's profile photoAnton Leontiev's profile photoEduardo Santana's profile photoDan Allen's profile photo
35 comments
 
I just updated the PDF to include the callout icons, in case you were wondering why they were missing.
 
Here's another tip. The Gnome help viewer, yelp, is a surprisingly good Docbook viewer. Use that to check your Docbook without having to make sense of the inhumane markup :)
 
Have you looked into http://code.google.com/p/wikbook/ made by +Julien Viet ? I think the interesting part of wikbook that I didn't see anywhere else was the fact that you can extract actual part of your example sources instead of copying/pasting. So you can actually run a testsuite on the samples that end up in your docs.
 
AsciiDoc gives you exactly that same functionality. You can do a basic include to grab a whole source document or you can use a plugin from the community to grab code by tags or line numbers. I'll definitely be exploring that.

I'll also check out wikibook, though I'm quite happy with AsciiDoc.
 
And look, now I can even write the name "AsciiDoc" correctly :) -- note the capital D.
 
Thanks for posting this. We are likely to adopt it at Axeda if we can get past the technical hurdles. I have been having challenges getting your sample to run, though. On Ubuntu 12.04, I ran:
sudo apt-get install asciidoc source-highlight
asciidoc javaeeworkshop.asciidoc

and got a lot of error output from source-highlight and a bunch of examples were blank in the output. I had similar issues in Cygwin on Windows.

What did you use to install asciidoc?
 
Awesome, I will definitely be there!
 
In fact, I just did a lightning talk that was right in line w/ the theme of your talk. Documentation is hard and we seem to choose tool that make it even harder. AsciiDoc is both relief and a world of possibilities.
 
Cool, got a link? Also, we might be able to externalize the toolchain soon for you to pitch in, now working on some better styling for the online version :)
 
Yep, I'll try to help where I can, but at the moment I'm trying to wrestle a large backlog.

One of the items in that backlog is publishing the slides I'm preparing/refining for this talk.
 
I've just discovered AsciiDoc a few hours ago and it's just UNBELIEVABLE!! It can do so much with so little effort! I share your enthusiasm  with this magnificent tool! I just can't wait to document some more xD
 
How did you create the table of contents in the sidebar? I ran asciidoc -f javaeeworkshop.conf -o tmp.html ./javaeeworkshop.asciidoc to generate an HTML file, but it just puts the TOC on top. Is there an easy way to create the scrollable menu on the side or is it necessary to manually code it in?
 
It's a commandline option, -a toc2. Here's the one I use:

asciidoc -b html5 -a icons -a theme=flask -a data-uri -a toc2 -a pygments

(you may need to specify the exact path to the theme files in the asciidoc installation, or you can copy them to ~/.asciidoc/themes)
 
Ok, my fault, had to upgrade asciidoc. Works now. Thanks. :)
The only problem is that the icons don't show up now for some reason. Where do you specify the path to the themes? I symlinked the themes folder into ~/.asciidoc and tried to specify the full path in theme=..., but it still doesn't work.
 
The icons are tricky. The icon path is a separate flag. However, you can put them in the theme to avoid having to do that. So here's what I do:

1. I create the following folder:
~/.asciidoc/themes

2. I copy the flask theme into that folder
3. I copy the contents of the images/icons folder from the AsciiDoc installation into ~/.asciidoc/themes/flask/icons/

Hope that helps.
 
All working now. :)

Added this to the asciidoc file:
========
JBoss Java EE 6 Workshop
========================
:backend: html5
:theme: flask
:toc2:
:icons:
:data-uri:
:pygments:
========
+ this in ~/.asciidoc/asciidoc.conf
========
[attributes]
iconsdir=/.../.asciidoc/images/icons/
# path has to be absolute to work, could be put into the asciidoc file, but I wanted it to work easily for new asciidoc files as well
========
Now I just need to run:
asciidoc javaeeworkshop.asciidoc

It seems asciidoc even does HTML slides with slidy! And to think I was planning to switch back from asciidoc to markdown just because github uses it with jekyll... :)
Now to see if it's possible to use jekyll just to add a header and footer to the generated .html page...
 
Hi Dan if you want to play even more with asciidoc and its conversions, see http://johnmacfarlane.net/pandoc/ Don't know if you already know pandoc but I am using it for generating documentation in various formats for NoSQLUnit project.

Alex.
 
Cool! Thanks for the tip Alex! I've come across Pandoc, but I didn't know of anyone using it.
 
On what files do you use it, specifically?
 
I write all documentation of NoSQLUnit in docformat, then using Maven with docbkx-maven-plugin and github plugin I generate the site and uploading it automatically to github pages. Finally I run Pandoc over docbook to generate the markdown file. Although now I am using DocBook I am thinking seriously to migrate to AsciiDoc.
 
For those of you following this thread, I've been collaborating with developers at GitHub to create an implementation of AsciiDoc for Ruby, named Asciidoctor. We're well on our way to being able to process most of the AsciiDoc syntax (at least anything you might have touched).

http://github.com/erebor/asciidoctor

Asciidoctor can output to HTML and DocBook out of the box at the moment. It's best feature, however, is that new backends can be created using any template language supported by Tilt (a template language abstraction library for Ruby). I've already implemented templates using Haml and Slim for both HTML and DocBook.

We should have a stable release of Asciidoctor out in early 2013. If you want to experiment it with it before then, grab the source and build it from GitHub.
 
And we can now render the AsciiDoc User Guide with Asciidoctor.
 
I'm developing a asciidoc server to generate a PDF, a chunked html version e slides for books under github.

It's very simple, the user must have a repository on github, with a book.asciidoc and a slide.asciidoc.

Then, the user goes to the server and paste his repository address, and click on generate. The server checkouts the git repository and generate the pdf, chunked  slide.

You can see it on:
https://github.com/edusantana/producao-computacao-ead-ufpb/tree/master/cgi

Look for github.html and pull-pdf.py.

This is just a cgi script on the server side. Very simple, but not safe yeat.
 
I also prefer the one from asciidoctor, I have worked with both, and totally agree with Dan about accurancy
 
Thanks Alex! Plus, it's easy to improve the one on asciidoctor.org. Just press the "Edit" button in the upper-right and propose an update.
 
"really digging deep into it's capabilities" ->
"really digging deep into its capabilities"
Eric F.
 
Have you tried txt2tags? It's very extensible (with preproc, regex), readable, logical (syntax is similar to dokuwiki and creole), and you can basically do everything you want with it.
Eric F.
+
1
2
1
 
+Roman Frołow
You can't really compare them. Txt2tags has a basic markup which should cover most of users' needs (heading, underline, strikethrough, code, raw marks etc), and for advanced use (such as footnotes for example, which isn't very useful for the web), instead of creating a fork of markdown, you can simply create rules in a template for processing your new markup, with the exports for the requested targets (LaTeX, lout, docbook etc). See https://code.google.com/p/txt2tags/wiki/FootNotes
Add a comment...