aafigure filter for AsciiDoc

Version: 1.1

Introduction

Aafigure (https://launchpad.net/aafigure) is an application for ASCII line art to image conversion. Using the AsciiDoc aafigure filter, ASCII line art can be embedded into AsciiDoc documents and processed into either PNG bitmap or SVG vector graphics.

Usage

The aafigure filter is invoked by setting the listing block or paragraph style (the first positional block attribute) to "aafigure".
The second positional attribute (named target) is optional, it sets the name of the generated image file. If this is not supplied a file name is automatically generated.
The default output format is SVG for DocBook and PNG for all other backends.
Additional well known aafigure options can be specified as named attributes. Refer to table below.

Table 1. Supported aafigure options
Option	Example	Default	Function
format	`["aafigure",format="png"]`	`svg` for DocBook, otherwise `png`	Image file format
scaling	`["aafigure",scaling="0.5"]`	`1.0`	aafigure image scaling [`scaling` is different to the DocBook backend’s image `scale` attribute!]
aspect	`["aafigure",aspect="0.7"]`	`1.0`	set aafigure aspect ratio
linewidth	`["aafigure",linewidth="4.0"]`	`2.0`	set linewidth (svg only)
foreground	`["aafigure",foreground="#ff1050"]`	`#000000`	foreground color
background	`["aafigure",background="#eeeeee"]`	`#ffffff`	background color
fill	`["aafigure",fill="#fff"]`	`#000000`	fill color (png only)
textual	`["aafigure",options="textual"]`		disable horizontal fill detection
proportional	`["aafigure",options="proportional"]`	`proportional`	use proportional font (default)
fixed	`["aafigure",options="fixed"]`		used fixed-width font

This AsciiDoc block:

["aafigure"]
-------------------------------------------------------------------------------
    +---------------+
    |A box with text|
    +---------------+
-------------------------------------------------------------------------------

renders:

Installation

In addition to AsciiDoc you will need to have installed:

The aafigure Python package (https://launchpad.net/aafigure)
The Python Imaging Library (PIL) package (http://www.pythonware.com/products/pil/)

The filter was developed and tested on Windows using aafigure 0.5, PIL 1.1.7 and AsciiDoc 8.6.3.

Known Issues

The Python Imaging Library (PIL) does a very poor job determining the correct font file on Windows platforms. It may generate warning and error messages as shown below if the font file names do not exactly match:

FT_Stream_Open: could not open `LiberationSans-Regular.ttf'
FT_Stream_Open: could not open `C:\WINDOWS\fonts\LiberationSans-Regular.ttf'
FT_Stream_Open: could not open `Arial.ttf'

FT_Stream_Open: could not open `LiberationMono-Regular.ttf'
FT_Stream_Open: could not open `C:\WINDOWS\fonts\LiberationMono-Regular.ttf'
FT_Stream_Open: could not open `Courier_New.ttf'
FT_Stream_Open: could not open `C:\WINDOWS\fonts\Courier_New.ttf'
WARNING: font not found, using PIL default font

To avoid the warning and error messages local copies of the GPL’d Liberation fonts are included in this filter distribution for convenience.