shaape 0.1.1

Shaape - Ascii art to image converter

README
======

Copyright
---------
Shaape - Ascii art to image converter
Copyright (C) 2012 Christian Goltz

This program 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 3 of the License, or
(at your option) any later version.

This program 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/>.

About Shaape
------------
Shaape processes ascii drawings of diagrams and converts them to pixel or
vector graphics. Shaape is meant to be used inside asciidoc documents to
enable writers to easily draw diagrams inside their asciidoc source documents.

The word *Shaape* itself is a neologism from *shape* and *ascii art*.

Why to use Shaape
~~~~~~~~~~~~~~~~~
There are already other projects, namely ditaa and aafigure, out there that
have a similar functionality as Shaape. However those are either inconsistent
between source and image, do not support diagonal lines or encourage you to use
too much markup inside the drawing.

Shaape supports a very natural form of ascii drawing (see the examples below)
and uses *absolutely no special markup* inside the drawing. Special markup
inside drawings makes those hard to read in the asciidoc document and thus have
to be avoided.

This way Shaape encourages you to keep an easy to read and clean drawing style
and makes sure your diagrams are consistent between the asciidoc source
document and it's output.

What is supported
~~~~~~~~~~~~~~~~~
- abritrary shapes
- arbitrary connected lines
- lines ending with arrows
- gradient filled polygons
- shadows for polygons, lines and arrows
- monospaced text in the whole drawing
- png rendering

What will be supported
~~~~~~~~~~~~~~~~~~~~~~
- rounded corners with the '*' character
- styles for background, polygons, lines and text including colors, fills and
line styles without markup inside the drawing
- text styles without markup inside the drawing
- svg rendering

What will *not* be supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- rotated text (cannot be displayed in ascii art)
- circles (cannot be displayed consistently in ascii art)

Dependencies
------------
- NetworkX python graph package
- pycairo

Installation
------------
There is no dedicated installation process at the moment, you can use the
source as it is.

`./Shaape.py` will print the usage help.

You can use `make install-filter` to install the asciidoc filter.

Usage
-----

Asciidoc integration
~~~~~~~~~~~~~~~~~~~~

Shaape uses an asciidoc block listing definition to integrate into asciidoc:
....
["shaape"]
---------------------------------------------------------------------
+--------+ +-------------+
| | \ /
| Hello |---> \ Goodbye /
| ;) | / \
| | / \
+--------+ +-------------+
---------------------------------------------------------------------
....

Drawing
~~~~~~~
You can use common known line art to draw polygons, open graphs and
arrows

Shaape makes use of `- | \ / + < > ^ v`.

Polygons are closed paths and automatically get filled. See following simple
examples for some polygons:

["shaape"]
---------------------------------------------------------------------
+--+ ++ /\ +----+
| | ++ / \ \ \
+--+ / \ \ \
\ / + +
\ / | |
\/ | +--+
+--+ /
| +-+ /
+---+ +-+
---------------------------------------------------------------------


Open graphs are all connected lines, that don't create closed paths. See
following examples for some open graphs:

["shaape"]
---------------------------------------------------------------------
--+----+------ |
| | +-+-+
| +------ / \
| + +
+----+------ / \ / \
+------ + + + +
+------ / \ / \ / \ / \
---------------------------------------------------------------------

Arrows can be combined with closed paths:
["shaape"]
---------------------------------------------------------------------
-> >-+----+------> |
<- ^ | | +-+-+
| | +------> / \
^ | <-+-> | + <-+->
| v | +----+------> / \ / \
v +------> + + + +
+------> | | | |
v v v v
---------------------------------------------------------------------

Text
~~~~
All words longer than one letter are processed and rendered as normal text.
If you need some special characters inside your words, than quote the whole
word. E.g. to print `|-|ello` you need to use `'|-|ello'`.
Again some examples:

["shaape"]
---------------------------------------------------------------------
+--------+ +-------------+ +------+
| | \ / |'.xml'|\
| Hello |----->\ Goodbye / | +-+
| ;) | / \ |'Docu-' |
| | / \ | 'ment'|
+---+----+ +------+------+ +---+----+
| | |
+------has nothing to do with---+
'a'<----+
v \
in>-+----+------> out1 | \
| | 'c'<--+-+-+->'b'<-+
| +------> out2 / \ |
| + + |
+----+------>'out!' / \ / \ |
+------> v_out + + + + |
+------> '->' / \ / \ / \ / \ |
'd' 'e' 'f' 'g' +-+
---------------------------------------------------------------------

Styles
~~~~~~

Although I basically want to disencourage you using fancy colors and styles,
there may be some use cases when you need it.

A style defines how an object is draw. Styles can be defined in a special
area below the diagram. This area starts with the identifier 'options:'.
On the next line the style description starts. The syntax for the style
description is http://www.yaml.org/spec/1.2/spec.html[YAML].

The style description should contain mappings from box names to a mapping of
attributes:

`boxname: { fill: [ red, flat], line : [ blue, dashed], shadow: off }`

The key of the outer mapping can consist of different names:

`box1,box2,box3: { fill: [ red, flat], line: [ blue, dashed, 3], shadow: off }`
Note: This is not conform to YAML)

.List of style attributes
- fill can contain:
* red, blue, green for the respective color
* list of 3 or 4 elements ranging from 0.0 to 1.0,
e.g. `[0.2, 0.3, 0.4, 0.5]`, for the respective rgba color
* flat, gradient
- line can contain:
* dashed, dotted, solid
* the same color mechanism as fills
* an integer or float describing the line width

["shaape"]
---------------------------------------------------------------------

+-------+
+-----+ /flatbox/
| abc | / /
+-----+--->+-------+
| +---+
v | |
+---+ |
/ style |
+---------+



options:
abc: {fill: [green], frame: [[0.6, 0.4, 0.4, 0.7], 3]}
flatbox,style: {fill: [[0.9, 0.9, 0.7, 0.3], flat, no-shadow], frame: [[0.2, 0.2, 0.0, 0.9], 2]}
---------------------------------------------------------------------

["shaape"]
---------------------------------------------------------------------
+--------+ +------+------+ +------+ +----+----+
| | \ / |'.xml'|\ ^ |abc |def |
| Hello +----->\ Goodbye / | +-+ | | + |
| ;) | / \ |'Docu-' |<--+--->+-+--+--+ |
| | / \ | 'ment'| | |'eh###'| |
+---+----+ +------+------+-->+---+----+ +----+----+
| | | +----+--+ +----+----+
+----- has nothing to do with --+ +flatbox| ++++++
+------+ 'a'<----+ \ | ++++++
| style| v \ +-----+
in>-+----+------> out1 +------+ | \ +->->->->->->-+
| | 'c'<--+-+-+->'b'<-+ | |
| +------> out2 / \ | ^ v
| + + | | arrowbox |
+----+------>'out!' / \ / \ | ^ v
+------> v_out + + + + | | |
+------> '->' / \ / \ / \ / \ | +-<-<-<-<-<-<-+
'd' 'e' 'f' 'g' +-+
options:
_default_: {fill: [[0.7, 0.9, 0.8], flat], frame: [[1, 0.2, 0.2, 0.5], dashed, 3], line: [[0.6, 0.5, 0.4], 2, no-shadow], arrow: [[0.3, 0.4, 0.5], no-shadow]}
flatbox,style:
fill:
- [0.9, 0.9, 0.7, 0.3]
- flat
- no-shadow
frame:
- [0.2, 0.2, 0.0, 0.9]
- 2
---------------------------------------------------------------------