Directory macros/latex/contrib/ditaa

= The LaTeX ditaa package

With this, you will not need to bring your diagrams outside your  ```.tex``` file and not to worry about wiring such files for diagrams, and tools (Microsoft Visio, PowerPoint, Libre Office tools, as such) from which they are created.

```
\begin{ditaa}{ditaa caption example}{ditaaexample}
    +-----+     +----+     +---+
    |Store+---->|This+---->|One|
    +--+--+     +----+     +---+
       |
       V
    +-----+
    |THIS |
    +--+--+
       |
       V
    +-----------+     +--+
    |another one+---->|Hi|
    +-----------+     +--+
\end{ditaa}

```

The source above will be converted into a following diagram and incorporated in your final PDF.

.Figure Rendered Ascii Art
[#img-sunset]
[caption="Figure 1: ",link=resources/rendered.png]
image::resources/rendered.png[Rendered Ascii Art,480,300]

== Prerequisites
https://github.com/asciidoctor[Asciidoctor @ *GitHub*]

* You need to have http://ditaa.sourceforge.net/[ditaa] installed. (Need to be able to run ```ditaa``` from your command line). Fortunately, recent package managers such as ```apt``` allow you to install it with a single command line ```sudo apt install ditaa```. ```brew``` let me do similar ```sudo brew isntall ditaa``` on my mac. For windows, sorry, please let me know how to do that...
* You need to give an option ```--shell-escape``` to your LaTeX compiler (such as ```pdflatex```, ```latex```, etc) command whichever you use.


== How to use

* Place the ```ditaa.sty``` file at the same directory as your ```.tex``` file.
* Create ```ditaa``` directory under the directory you have for the other non-ditaa images. This package will create ```.ditaa``` and ```.png``` files.
* Do ```usepackage[imagepath=IMAGEPATH]{ditaa}``` beffore ```\begin{document}```. The IMAGEPATH is the directory you have images.
* Compile your  ```.tex``` files as usual, but giving  ```--shell-escape``` option to your ```(pdf)latex``` command.

== Tips
Online sites such as [ascii-flow](http://stable.ascii-flow.appspot.com/#Draw) will be your friends!

== Future Works
* Make it possible to define caption and filename independently.
* ~~Improve the way to define resource directory.~~
* ~~Make it possible to specify image size.~~ (Now you can specify image width. See the example)
* I want to use this in OverLeaf. Publish in CTAN? Help me. I'm a LaTeX newbie.

== References
* https://github.com/deselaers/latex-beamerposter[latex-beamerposter]: I learned a lot from this; such as how to package my .sty, how to organize directories under my repo for LaTeX style package, etc.