donatedonate
(((-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.
There are several reasons why I did this:
(((-intro-))) (((-download-))) (((-usage and syntax-))) (((-friends-))) (((-contact-)))
The latest version of ditaa can be obtained from its SourceForge 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.
(((-intro-))) (((-download-))) (((-usage and syntax-))) (((-friends-))) (((-contact-)))
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 processing | Common edge separation (default) |
No separation (with the -E option) |
-e,--encoding <ENCODING> The encoding of the input file.
-h,--html In this case the input is an HTML file. The
contents of the <pre class="textdiagram"> tags
are rendered as diagrams and saved in the
images directory and a new HTML file is
produced with the appropriate <img> tags.
See the HTML section.
--help Prints usage help.
-o,--overwrite If the filename of the destination image
already exists, an alternative name is chosen.
If the overwrite option is selected, the image
file is instead overwriten.
-r,--round-corners Causes all corners to be rendered as round
corners.
-s,--scale <SCALE> A natural number that determines the size of
the rendered image. The units are fractions of
the default size (2.5 renders 1.5 times bigger
than the default).
-S,--no-shadows Turns off the drop-shadow effect.
-t,--tabs <TABS> Tabs are normally interpreted as 8 spaces but
it is possible to change that using this
option. It is not advisable to use tabs in
your diagrams.
-v,--verbose Makes ditaa more verbose.
If you use / and \ to connect corners, they are rendered as round corners:
/--+ | | +--/ |
 |
| Before processing | Rendered |
Color codes can be used to add color to the diagrams. The syntax of color codes is
cXXX
where XXX is a hex number. The first digit of the number represents the red compoment of the color, the second digit represents green and the third blue (good ol' RGB). See below for an example of use of color codes:
/----\ /----\ |c33F| |cC02| | | | | \----/ \----/ /----\ /----\ |c1FF| |c1AB| | | | | \----/ \----/ |
 |
| Before processing | Rendered |
This can become a bit tedious after a while, so there are (only some for now) human readable color codes provided:
Color codes /-------------+-------------\ |cRED RED |cBLU BLU | +-------------+-------------+ |cGRE GRE |cPNK PNK | +-------------+-------------+ |cBLK BLK |cYEL YEL | \-------------+-------------/ |
 |
| Before processing | Rendered |
As you can see above, if a colored shape contains any text, the color of the text is adjusted according to the underlying color. If the undelying color is dark, the text color is changed to white (from the default black).
Note that color codes only apply if they are within closed shapes, and they have no effect anywhere outside.
ditaa recognises some tags that change the way a rectangular shape is rendered. All tags are between { and }. See the table below:
| Name | Original | Rendered | Comment |
|---|---|---|---|
| Document |
+-----+
|{d} |
| |
| |
+-----+
|
 |
Symbol representing a document. |
| Storage |
+-----+
|{s} |
| |
| |
+-----+
|
 |
Symbol representing a form of storage, like a database or a hard disk. |
| Input/Output |
+-----+
|{io} |
| |
| |
+-----+
|
 |
Symbol representing input/output. |
Any lines that contain either at least one = (for horizontal lines) or at least one : (for vertical lines) are rendered as dashed lines. Only one of those characters can make a whole line dashed, so this feature "spreads". The rationale behind that is that you only have to change one character to switch from normal to dashed (and vice versa), rather than redrawing the whole line/shape. Special symbols (like document or storage symbols) can also be dashed. See below:
----+ /----\ +----+
: | | : |
| | | |{s} |
v \-=--+ +----+
|
|
| Before processing | Rendered |
If * is encountered on a line (but not at the end of the line), it is rendered as a special marker, called the point marker (this feature is still experimental). See below:
*----* | | /--* * * | | | -*--+ *----* |
 |
| Before processing | Rendered |
(This section is still being written)
If the pattern ' o XXXXX' is encountered, where XXXXX is any text, the 'o' is interpreted and rendered as a bullet point. Note that there must be a space before the 'o' as well as after it. See below:
/-----------------\ | Things to do | | cGRE | | o Cut the grass | | o Buy jam | | o Fix car | | o Make website | \-----------------/ |
 |
| Before processing | Rendered |
(((-intro-))) (((-download-))) (((-usage and syntax-))) (((-friends-))) (((-contact-)))
Here is a list of projects that are related to ditaa and add to its functionality:
Here's a list of projects that are somehow related to ditaa, and could prove useful/relevant while using it:
(((-intro-))) (((-download-))) (((-usage and syntax-))) (((-friends-))) (((-contact-)))
The author of ditaa is Stathis Sideris. Please feel free to contact me with any questions, suggestions, bug fixes, hate mail etc. at:
stathissideris {at} users {dot} sourceforge {dot} net
Thanks to John Tsiombikas and Leonidas Tsampros for beta testing of ditaa. :)
Thanks to Steve Purcell for writing JArgs.
Thanks to Mr. Jericho for writing Jericho HTML Parser.
You might also be interested in my personal website.