This text is taken from the Asciidoc home page.

Asciidoc is a text document format for writing short documents, articles, books and UNIX man pages. AsciiDoc files can be translated to HTML and DocBook markups using the asciidoc(1) command.

This text is taken from the Dia home page.

Dia is a GTK+ based diagram creation program for GNU/Linux, Unix and Windows released under the GPL license. Dia is roughly inspired by the commercial Windows program 'Visio', though more geared towards informal diagrams for casual use.

Screenshots for the Dia program.

Dia and Asciidoc is available for different linux distributions, I installed them in Ubuntu using

$ sudo aptitude install asciidoc dia

They can also be installed on OS X using, for example, the MacPorts project, in which case you write:

$ sudo port install asciidoc
$ sudo port install dia

And then wait for a while when everything compiles..

The solution

Asciidoc has the possibility to import files when generating the documentation, which is a nice feature when you don't want to duplicate information and have it up-to-date. For example, it can import images, show the content of XML files, generate diagrams using various graphviz syntax and so on.

Dia can export its diagrams to various image formats and this can be done on the command line. Using this feature of Dia it is actually possible to have Asciidoc generating image files from Dia's file format, here is how to do it:

Step one, creating the Asciidoc plugin

As asciidoc cannot read the native Dia's file format, it needs to trigger the export functionality of Dia. It is possible to extend Asciidoc by writing a filter, which is just a shell command reading from standard input and writing to standard output. In this specific case, the parameters to the shell process will be used and the image template functionality existing in Asciidoc will take care of reading from the generated image.

Asciidoc reads filter configuration files from four different locations in the following order:

1. It looks in the user’s $HOME/.asciidoc/filters directory.
2. The global filters directory (usually /etc/asciidoc/filters or /usr/local/etc/asciidoc) directory is searched.
3. It looks in the asciidoc(1) ./filters directory.
4. It relies on the executing shell to search the environment search path ($PATH).

Here I will put the filter in my home directory. Start with creating the document structure:

   $HOME/.asciidoc/filters/dia

In the dia directory, create the file dia-filter.conf with the following content:

#
# AsciiDoc Dia filter configuration file.
#
# Version: 0.1

[blockdef-listing]
dia-style=template="dia-block",subs=(),posattrs=("style","file","target","size"),filter='dia -t png -e "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" "{outdir}/{file}" {size?-s {size}} > /dev/null'

[dia-block]
template::[image-blockmacro]

Now Asciidoc has been extended with a filter that takes the parameters file, target and size where the last parameter is optional. The next section describes how to use this filter in Asciidoc.

Step two, Import Dia diagram files in Asciidoc

To use the dia filter in Asciidoc, the following syntax is used:

[dia "infile.dia", "outfile.png", "x480"]
-------------------------------
-------------------------------

The syntax above will trigger the filter and provide 'infile.dia' as source which should be a diagram saved in Dia, 'outfile.png' is the image file to be generated and create a 480 pixels wide image. Writing the size as '480x' will specify the height of the image.
Don't forget the dashes, otherwise the filter will not be triggered.