Creating diagrams for documentation can be a pain, and more critically it
interrupts the flow of writing. There's a way to create these diagrams in
AsciiDoc without having to open a separate application. Actually, there are
a few ways, I'll just give the most well-known example: ditaa - diagrams
through Ascii art.
ditaa is a small command-line utility written in Java, that can convert
diagrams drawn using ascii art ('drawings' that contain characters that
resemble lines like | / - ), into proper bitmap graphics.
There is a filter available for AsciiDoc that will process blocks of text
that are marked as ditaa diagrams using ditaa and insert the result as an
image.
Here's how you could create the first diagram from the TicketMonster
tutorial using ditaa within AsciiDoc.
[ditaa, single-page-app.png, 2]
----
/--------------\ /--------------\
| Single HTML5 | | REST |
| |----->| |
| page | | services |
\--------------/ \--------------/
----
You might be thinking that getting all those pipes lined up is a bit of a
pain. The first trick is to enable arbitrary positing of the cursor so you
don't have to hit the space bar a zillon times. But even better than that,
there's AsciiFlow ->
http://asciiflow.com.
Just thought I'd give you a heads up.
-Dan
p.s. The ditaa-AsciiDoc integration could be useful for the CDI
specification as well.
--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597
http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction