The idea is to parse ASCII art images, embedded in reST documents and output an image. This would mean that simple illustrations could be embedded as ASCII art in the reST source and still look nice when converted to e.g. HTML
Files:
The aafigure module contains code to parse ASCII art figures and create a list of of shapes. The different output modules can walk trough a list of shapes and write image files.
./rst2html.py README.txt >README.html
This results in the README.html file and a .svg file for each aafigure.
Display the resulting README.html file in a SVG capable browser. It has been tested with Firefox 1.5.
This code in a reST document that is processed with the enhanced rst2html.py looks like this:
.. aafigure::
-->
Which results in an image like this:
The aafigure directive has the following options:
:scale: <float> enlarge or shrink image
:line_width: <float> change line with (svg only currently)
:line_format: <str> choose backend/output format: 'svg', 'png', all bitmap formats that PIL supports can be used but only few make sense. Line drawings have a good compression and better quality when saved as PNG rather than a JPEG. The best quality will be achieved with SVG, tough not all browsers support this vector image format at this time.
:foreground: <str> foreground color in the form #rgb or #rrggbb
:background: <str> background color in the form #rgb or #rrggbb (not for SVG output)
:fill: <str> fill color in the form #rgb or #rrggbb
:name: <str> use this as filename instead of the automatic generated name
:aspect: <float> change aspect ratio. Effectively it is the width of the image that is multiplied by this factor. The default setting 1 is useful when shapes must have the same look when drawn horizontaly or verticaly. However, :aspect: 0.5 looks more like the original ASCII and even smaller factors may be useful for timing diagrams and such. But there is a risk that text is cropped or is draw over an object beside it.
The stretching is done before drawing arrows or circles, so that they are still good looking.
The - and | are normaly used for lines. _ can also be used. It is a slightly longer line than the - and it's is drawn a bit lower. = gives a thicker line. The later two line types can only be drawn horizontaly.
---- | ___
| -- ___| ===
It is also possible to draw diagonal lines. Their use is somewhat restricted tough. Not all cases work as expected.
And drawing longer diagonal lines with different angles looks ugly...
Arrow styles are:
---> | | | | | | ---< | | | | | | ---o ^ V v o O # ---O ---#
Boxes are automaticaly draw when the edges are made with +, filled boxes are made with X (must be at least two units high or wide). It is also possibe to make rounded edges in two ways:
+-----+ XXX /--\ -- | | | XXX | | / / +-----+ XXX \--/ | --
Upper case characters generate shapes with borders, lower case without border. Fills must be at least two characters wide or high. (This reduces the chance that it is detected as Fill instead of a string)
Complex shapes can be filled:
The images may contain text too. There are different styles to enter text:
direct
Bby default are repeated characters detected as fill:
Hello World dd d
d
quoted
Text between quotes has piority over any graphical meaning:
"Hello World" dd d
d
", ' and \` are all valid quotation marks. The quotes are not visible in the resulting image. This not only disables fills (see below), it also treats -, | etc as text.
textual option
The :textual: option disables horizontal fill detection. Fills are only detected when they are verticaly at least 2 charcacters high:
Hello World dd d
d
* { }
Symbol detection: scan for predefined shapes in the ASCII image and output them as symbol from a library
Symbol libraries for UML, flowchart, electronic schematics, ...
The way the image is embedded is a hack (inserting a tag trough a raw node...)
Search for ways to bring in color. Ideas:
have an :option: to set color tags. Shapes that touch such a tag inhertit it's color. The tag would be visible in the ASCII source tough:
.. aafigure:: :colortag: 1:red, 2:blue 1---> --->2:color: x,y,color but counting coordinates is no so fun
drawback: both are complex to implement, searching for shapes that belong together. it's also not always wanted that e.g. when a line touches a box, both have the same color
aafigure probably needs arguments like font-family, ...
Punctuation not included in strings (now a bit improved but if it has a graphical meaning , then that is chooses, even if it makes no sense), underlines in strings are tricky to detect...
Dotted lines? ...
Group shapes that belong to an object, so that it's easier to import and change the graphics in a vector drawing program.
Path optimizer, it happens that many small lines are output where a long line could be used.
BSD
To compare input and output, look at the sources of this file.
Different arrow types:
Boxes and shapes:
No not realy, yet. But you get the idea.
It would be cool if it could display simple schematics.
Here is a complete circuit with different parts:
Here is one with descriptions: