Introduction

You found this page because you are looking for more information on installing asciio and ditaa, and then modifying asciio to better interact with ditaa. Well you came to the right place. This guide will take you step-by-step through installing both tools, and modifying asciio to output diagrams to ditaa.

Installation

Ditaa

Thanks to our good friend David Paleino over working on Debian, we have handy-dandy .deb to install that make installation very easy (if you use a Debian based distribution).

Debian Sid

If you are using Debian Sid, you can install ditaa by typing:

apt-get install ditaa

Ubuntu 9.10

ditaa is not packaged for Ubuntu yet. You can download the .deb here from the Debian site. Install using (where ditaa_0.9+ds1-1_all.deb is the version of the .deb you download):

sudo dpkg -i ditaa_0.9+ds1-1_all.deb

Or you can download the .jar file directly from the ditaa folks. To install manually, just extract the files to your hard drive. Remember the location, as you will need it later in the modification. I've installed the jar into /home/thomas/programs/asciio-ditaa/

Modifying asciio

Now that you are familiar with ditaa and asciio, you may see the benefit of outputting asciio text files that are compatible with ditaa without modification. Or better yet, generate your diagrams for you when you save :). This section will explain how to do all of that and more!

Adding in a Ditaa Stencil

You will need to create a new stencils file to create boxes and arrows that are compatible with ditaa (you could optionally modify the standard files if you will only use asciio for ditaa purposes). I got the idea for the modifications from here: http://strawp.net/archive/geeking-out-with-diagrams-in-ascii/

A Standard Box

Go to the App/Asciio/setup/stencils (in the /usr/share/perl5/ or /usr/share/perl/5.10.0/) directory, and find the asciio file. Using for favourite editor, copy and paste the standard box code into a new file called ditaa. Then make the following changes to the standard box code in this new file:

To change the corners, modify line 14/33 and change . to + and modify line 17/36 and change \' to +.

Then modify lines 5 and 7 in the same way. Replace the . with + and the \' with +.

Or you could optionally just copy and paste the completed code below (the $VAR1 = [ is only needed once, and just starts off the file, the ]; at the end of the block, ends the file. All bless calls should be between these lines) :

Add Colours and Special Shape Codes

All of the above will give you the core functionality of ditaa into asciio. But what about some basic colour tags, and shape codes. I've created a special stencil file for those. You can copy this below, and place it in a file called ditaatags next to the asciio stencil file.

Modifying Saving

It is nice to generate a text file of the data in case you need to make further tweaks before running it through ditaa. It is also required if you want to generate .pngs on the fly of your diagrams.

Go to App/Asciio/setup/actions and load up the file.pl file.

On line 65, replace the original saving code with the following:

#$new_title = $self->save_with_type($elements_to_save, $type, $file_name) ;## Regardless of previous stuff, save one asciio file and one asciio.<ext>.txt ascii file## Courtesy of Strawp of http://strawp.net/archive/geeking-out-with-diagrams-in-ascii/$new_title=$self->save_with_type($elements_to_save,"asciio",$file_name);$new_title=$self->save_with_type($elements_to_save,"txt",$file_name.".txt");## Run ditaa to convert text version into nice copy## Use this if you have Proc::Background available. Otherwise, use the system call below.#use Proc::Background;#my $proc1 = Proc::Background->new("c:\\bin\\ditaa.bat \"".$file_name.".txt\" \"".$file_name.".png\"");#my $proc1 = Proc::Background->new("java -jar /home/thomas/programs/ditaa/ditaa0_9.jar \"".$file_name.".txt\" \"".$file_name.".png\"");## This call converts while saving. Slows down save time. Replace the path below with your path to ditaa.jar## You can add any special parameters here that you commonly use as well.## Use this command if you unzipped the .jar filesystem("java -jar /home/thomas/programs/asciio-ditaa/ditaa0_9.jar \"".$file_name.".txt\"\"".$file_name.".png\"");## Use this command if you installed the .deb.#system("ditaa \"".$file_name.".txt\" \"".$file_name.".png\"");

Using the New Setup

Now that you have made all of your tweaks, you are ready to start using your asciio/ditaa combo! Start by making a simple diagram. Here is one below:

Notice when you save this file for the first time:

Several files are created at first. As well as our rendered image.

Now, lets spice it up with some colour and some shapes. Use the right click menu to add the document tag to each of the items labelled document. To do this you will need to:

Right click and select stencils → ditaatags → shapes → document

Drag the {d} over the first document. I suggest you group any shapes, and shape modifiers by using CTRL+G once you set them up. If you do this, all of your pieces will move around if you have to tweak your image. Grouping involves selecting each item (hold shift while clicking each item), then press CTRL+G on your keyboard. This will cause this group of items to change background colour, and if you move one item, they will all move together. (You can ungroup by pressing CTRL+U)

Add another {d} to the other document.

If your item is falling behind the item you want, you can press CTRL+F to bring it to the foreground. Or CTRL+B to push the item on top into the background.

Now lets add some colour. Right click, and add some colour tags to the documents. As you save, you will notice the .png updates automatically.

Here is your final work of art:

Troubleshooting

asciio Won't Load File

I've noticed that if you modify the stock asciio shapes (either through the gui itself, or in the stencils file) often times if you launch asciio, and then try to load a file with altered shapes, it will fail to load. It generates this output in the terminal:

asciio Forgets Where I Saved

When loading asciio for the first time, and saving, I find that asciio forgets where I saved the document. It always returns to the original launching location.

To avoid this, I'd recommend that after your first save, you reopen asciio by using one of the two procedures mentioned above. This will allow it to remember where you are working, and the Save function will work correctly.