TXGR

TXGR is a sample PHP library that can convert diagrams drawn using ascii art ('drawings' that contain characters that resemble lines like | / - ), into proper bitmap graphics.

It was inspired by ditaa. Unfortunately I was never able to get ditaa to work, and I did not like the fact that it was a java application, so I wrote this instead.

This is best explained with the following (ditaa) example:

+--------+   +-------+    +-------+
|        | --+ ditaa +--> |       |
|  Text  |   +-------+    |diagram|
|Document|   |!magic!|    |       |
|     {d}|   |       |    |       |
+---+----+   +-------+    +-------+
    :                         ^
    |       Lots of work      |
    +-------------------------+

After conversion using TXGR, the above becomes

TXGR interprets ascci art and translates it into bitmaps. It also uses special markup syntax to increase the possibilities of shapes and symbols that can be rendered.

TXGR is open source and free software (free as in free speech), since it is released under the GPL license.

BUT WHY? Does this thing have any real use?

There are several reasons why I did this:

1. Simply for hack value. I wanted to know if/how it could be done and how easily.
2. Could not get ditaa to work. Also, it is useful for using in Hosting services that only allow PHP code.

Download

The current version is 0.01. Be warned that this is a initial release and a beta version. Use it at your own risk!

Files can be found in SourceForge

Usage

This library requires the php GD extension. To use simply copy txgr.php to somewhere accessible by your web server. Then use:

require_once("txgr.php");

You can the use:

# This will take the markup text in $txt and parse it
$cells = txgr_parse($txt);
# This will render the parsed cells as a PNG
txgr_gd($cells);
# You can optionally pass a file name to output the PNG file to
txgr_gd($cells,$output_file);

See the include sample files for example usage.

Command-Line usage

The distribution contains also a simple command line tool that combines PHP markdown extra with TXGR so that you can generate HTML files containing images on the command line.

The HTML documentation was generated that way.

The usage is as follows:

$ txgr-cli.php _[--verbose|--quiet]_ _[-o outputdir]_ _[-b baseurl]_ _[files]_

Examples:

$ txgr-cli.php -o imgs < README.txt > README.html

Or

$ txgr-cli.php --verbose README.txt

Syntax

Round corners

If you use / and \ to connect corners, they are rendered as round corners:

Input:

/--+
|  |
+--/

Output:

Color

Color codes can be used to add color to the diagrams. The syntax of colors codes is:

cXXX

where XXX is a decimal number. With each digit representing a different RGB color component.

Input:

/----\ /----\
|c339| |c802|
|    | |    |
\----/ \----/

/----\ /----\
|c199| |c178|
|    | |    |
\----/ \----/

Output:

Tags

TXGR recognizes some tags that change the way a rectangular shape is rendered. All tags are between { and }. See the examples below:

Document:

+---------+
| {d}     |
|         |
|         |
+---------+

Storage:

+---------+
| {s}     |
|         |
|         |
+---------+

Input/Output:

+---------+
| {i}     |
|         |
|         |
+---------+

Grayed lines

Any lines that contain either at least one = (for horizontal lines) or at least one : (for vertical lines) are rendered as grayed lines. Only one of those characters can make a whole line dashed, so this feature "spreads". The rationale behind that is that you only have to change one character to switch from normal to dashed (and vice versa), rather than redrawing the whole line/shape. Special symbols (like document or storage symbols) can also be dashed. See below:

Input:

----+  /----\  +----+
    :  |    |  :    |
    |  |    |  |{s} |
    v  \-=--+  +----+

Bullet points

If the pattern ' o XXXXX' is encountered, where XXXXX is any text, the 'o' is interpreted and rendered as a bullet point. Note that there must be a space before the 'o' as well as after it. See below:

Input:

/-----------------\
| Things to do    |
| c080            |
| o Cut the grass |
| o Buy jam       |
| o Fix car       |
| o Make website  |
\-----------------/

Output:

Emacs Support

You can edit ascii diagrams using Emacs if you enable artist-mode.

Ditaa differences

TXGR does not support all the markup options that ditaa does. These are the differences between TXGR and ditaa.

• Color specifications are in decimal and do not allow for mnemonics. They work outside shapes but they do not do foreground color inversion.
• No shadows are rendered. And shapes are not separated.
• The {io} tag has been renamed to {i}. Also, this is rendered wrongly.
• Dashed lines are implemented as shaded lines. And they expand across objects.
• No point markers are supported.
• Implemented in PHP instead of Java as a single 19K file.

There are lot more features that ditaa does so you are better off just using that.

LICENSE

Copyright (C) 2009 Alejandro Liu Ly

txgr is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

txgr is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/

This distribution makes use of PHP Markdown. Markdown is free software, available under the terms of a BSD-style open source license. See the PHP Markdown Website for more details.