The "ditaa" environment

ditaa.sty

% 'ditaa' package
%
% (c) Hiroshi Ukai
%
%% This program can be redistributed and/or modified under the terms
%% of the LaTeX Project Public License Distributed from CTAN archives
%% in directory macros/latex/base/lppl.txt.
%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{ditaa}
[2018/09/27 v0.01 LaTeX package for embedding ditaa style ascii art]

\RequirePackage{fancyvrb}
\RequirePackage{graphicx}
\RequirePackage{kvoptions}

\DeclareStringOption[]{imagepath}
\ProcessKeyvalOptions*

%@formatter:off (This line indicates IntelliJ that formatter should be off before this)
\newenvironment{ditaa}[3][\columnwidth]
    {
        \def\ditaacaption{#2}
        \def\ditaastem{#3}
        \def\ditaadir{\ditaa@imagepath/ditaa}
        \def\ditaafile{\ditaadir/\ditaastem.ditaa}
        \def\ditaafigwidth{#1}
        \VerbatimOut{\ditaafile}}
    {\endVerbatimOut
        \immediate\write18{ditaa -E "\ditaafile" "\ditaadir/\ditaastem.png"}
        \begin{figure}[h]
            \begin{center}
                \includegraphics[width=\ditaafigwidth]{\ditaadir/\ditaastem.png}
                \caption{\ditaacaption}
            \end{center}
            \label{fig:\ditaastem}
        \end{figure}
    }
%@formatter:on (This line indicates IntelliJ that formatter should be off before this)
%--------------------------------------------------

\endinput
%%
%% End of file `ditaa.sty'.

Prerequisites

• You need to have 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... Maybe scoop is useful?
• You need to give an option --enable-write18 to your pdflatex or latex 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 --enable-write18 option to your (pdf)latex command.

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 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.

Tips

Online sites such as ascii-flow 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.

A full example

A complete example is as follows. Compile it with pdflatex --enable-write18 filename.tex.

% Preamble
\documentclass[11pt]{article}

% Packages
\usepackage{a4wide}
\def\imagepath{./resources/graphics}
\usepackage[imagepath=\imagepath]{ditaa}
\graphicspath{ {\imagepath/} }

\begin{document}
    This is a ditaa diagramm example.
    \begin{ditaa}{ditaa caption example}{ditaaexample}
        +--------+   +-------+    +-------+
        |        | --+ ditaa +--> |       |
        |  Text  |   +-------+    |diagram|
        |Document|   |!magic!|    |       |
        |     {d}|   |       |    |       |
        +---+----+   +-------+    +-------+
            :                         ^
            |       Lots of work      |
            +-------------------------+
    \end{ditaa}
    Enjoy!
    And you can even specify image width like this Figure.\ref{fig:ditaaexample2}.
     \begin{ditaa}[6cm]{ditaa caption example2}{ditaaexample2}
       +---------+
       | cBLU    |
       |         |
       |    +----+
       |    |cPNK|
       |    |    |
       +----+----+
    \end{ditaa}
\end{document}