ditaa ASCII art to diagram


DIagrams Through Ascii Art

by Stathis Sideris

(((-intro-))) (((-download-))) (((-usage and syntax-))) (((-friends-))) (((-contact-)))

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. This is best illustrated by the following example — which also illustrates the benefits of using ditaa in comparison to other methods 🙂

+——–+ +——-+ +——-+ | | –+ ditaa +–> | | | Text | +——-+ |diagram| |Document| |!magic!| | | | {d}| | | | | +—+—-+ +——-+ +——-+ : ^ | Lots of work | +————————-+ After conversion using ditaa, the above file becomes:

ditaa interprets ascci art as a series of open and closed shapes, but it also uses special markup syntax to increase the possibilities of shapes and symbols that can be rendered.

ditaa is open source and free software (free as in free speech), since it is released under the GPL license.

BUT WHY? Does this thing have any real use?

There are several reasons why I did this:

Simply for hack value. I wanted to know if/how it could be done and how easily.Aesthetic reasons and legacy formats: there are several old FAQs with ascii diagrams lying out there. At this time and age ascii diagrams make my eyes hurt due to their ugliness. ditaa can be used to convert them to something nicer. Although ditaa would not be able to convert all of them (due to differences in drawing ‘style’ in each case), it could prove useful in the effort of modernising some of those documents without too much effort. I also know a lot of people that can make an ascii diagram easily, but when it gets to using a diagram program, they don’t do very well. Maybe this utility could help them make good-looking diagrams easily/quickly.Embedding diagrams to text-only formats: There is a number of formats that are text-based (html, docbook, LaTeX, programming language comments), but when rendered by other software (browsers, interpreters, the javadoc tool etc), they can contain images as part of their content. If ditaa was intergrated with those tools (and I’m planning to do the javadoc bit myself soon), then you would have readable/editable diagrams within the text format itself, something that would make things much easier. ditaa syntax can currently be embedded toHTML.Reusability of “code”: Suppose you make a diagram in ascii art and you render it with version 0.6b of ditaa. You keep the ascii diagram, and then version 0.8 comes out, which features some new cool effects. You re-render your old diagram with the new version of ditaa, and it looks better, with zero effort! In that sense ditaa is a diagram markup language, with very loose syntax.


(((-intro-))) (((-download-))) (((-usage and syntax-))) (((-friends-))) (((-contact-)))

The latest version of ditaa can be obtained from itsSourceForge project page.

You can checkout the code using:

   svn co https://ditaa.svn.sourceforge.net/svnroot/ditaa ditaa

You can also browse the code online.

Usage and syntax

(((-intro-))) (((-download-))) (((-usage and syntax-))) (((-friends-))) (((-contact-)))

Command line

You need the latest Java runtimes (JRE) to use ditaa. The best anti-aliasing can be achieved using Java 1.5 or higher.

To start from the command line, type (where XXX is the version number):

java -jar ditaaXXX.jar

You will be presented with the command-line options help:

-A,–no-antialias Turns anti-aliasing off. -d,–debug Renders the debug grid over the resulting image. -E,–no-separation Prevents the separation of common edges of shapes. You can see the difference below: +———+ | cBLU | | | | +—-+ | |cPNK| | | | +—-+—-+ Before processingCommon edge
separation (default)No separation
(with the -E option) -e,–encoding The encoding of the input file. -h,–html In this case the input is an HTML file. The contents of the

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s