sandbox/aafigure/README.txt

   1 =================
   2  aafigure README
   3 =================
   4
   5 Overview
   6 ========
   7
   8 The idea is to parse ASCII art images, embedded in reST documents and output
   9 an image. This would mean that simple illustrations could be embedded as
  10 ASCII art in the reST source and still look nice when converted to e.g. HTML
  11
  12
  13 Installation
  14 ============
  15
  16 To install aafigure, you need to have administrator rights on your
  17 system (be root), and ``setuptools`` (often packaged as
  18 ``python-setuptools``) must be installed.
  19
  20 Type "``python setup.py install``" to install aafigure.
  21 Alternatively, type "``python setup.py develop``" to only install a
  22 reference to the aafigure source directory.  This is useful if you
  23 want to hack the source.
  24
  25 After that, the ``aafigure`` directive will be available site-wide.
  26
  27
  28 Implementation
  29 ==============
  30
  31 Files:
  32
  33 ``aafigure.py``
  34     ASCII art parser. This is the main module.
  35
  36 ``aafigure_directive.py``
  37     Implmements the ``aafigure`` Docutils directive that takes these
  38     ASCII art figures and generates a drawing.
  39
  40 ``aa.py``
  41     ASCII art output backend. Intended for tests, not for the end user.
  42
  43 ``pdf.py``
  44     PDF output backend. Depends on reportlab.
  45
  46 ``pil.py``
  47     Bitmap output backend. Using PIL, it can write PNG, JPEG and more formats.
  48
  49 ``rst2html.py``
  50     Patched version that adds the ``aafigure`` Docutils directive.
  51
  52 ``svg.py``
  53     SVG output backend.
  54
  55
  56 The ``aafigure`` module contains code to parse ASCII art figures and create
  57 a list of of shapes. The different output modules can walk trough a list of
  58 shapes and write image files.
  59
  60
  61 Usage
  62 =====
  63 ::
  64
  65     ./rst2html.py README.txt >README.html
  66
  67 This results in the ``README.html`` file and a ``.svg`` file for each
  68 ``aafigure``.
  69
  70 Display the resulting ``README.html`` file in a SVG capable browser. It has
  71 been tested with Firefox 1.5.
  72
  73
  74
  75 Short introduction
  76 ==================
  77 This code in a reST document that is processed with the enhanced ``rst2html.py``
  78 looks like this::
  79
  80     .. aafigure::
  81
  82         -->
  83
  84 Which results in an image like this:
  85
  86 .. aafigure::
  87
  88     -->
  89
  90 The ``aafigure`` directive has the following options:
  91
  92 - ``:scale: <float>``   enlarge or shrink image
  93
  94 - ``:line_width: <float>``   change line with (svg only currently)
  95
  96 - ``:format: <str>`` choose backend/output format: 'svg', 'png', all
  97   bitmap formats that PIL supports can be used but only few make sense. Line
  98   drawings have a good compression and better quality when saved as PNG
  99   rather than a JPEG. The best quality will be achieved with SVG, tough not
 100   all browsers support this vector image format at this time.
 101
 102 - ``:foreground: <str>``   foreground color in the form ``#rgb`` or ``#rrggbb``
 103
 104 - ``:background: <str>``   background color in the form ``#rgb`` or ``#rrggbb``
 105   (*not* for SVG output)
 106
 107 - ``:fill: <str>``   fill color in the form ``#rgb`` or ``#rrggbb``
 108
 109 - ``:name: <str>``   use this as filename instead of the automatic generated
 110   name
 111
 112 - ``:aspect: <float>``  change aspect ratio. Effectively it is the width of the
 113   image that is multiplied by this factor. The default setting ``1`` is useful
 114   when shapes must have the same look when drawn horizontally or vertically.
 115   However, ``:aspect: 0.5`` looks more like the original ASCII and even smaller
 116   factors may be useful for timing diagrams and such. But there is a risk that
 117   text is cropped or is draw over an object beside it.
 118
 119   The stretching is done before drawing arrows or circles, so that they are
 120   still good looking.
 121
 122 - ``:proportional: <flag>``  use a proportional font instead of a monospaced
 123   one.
 124
 125
 126 Lines
 127 -----
 128 The ``-`` and ``|`` are normally used for lines. ``_`` and ``~`` can also be
 129 used. They are slightly longer lines than the ``-``. ``_`` is drawn a bit
 130 lower and ``~`` a bit upper. ``=`` gives a thicker line. The later three line
 131 types can only be drawn horizontally.
 132 ::
 133
 134   ---- |         ___  ~~~|
 135        | --  ___|        |    ===
 136                          ~~~
 137
 138 .. aafigure::
 139
 140   ---- |         ___  ~~~|
 141        | --  ___|        |    ===
 142                          ~~~
 143
 144 It is also possible to draw diagonal lines. Their use is somewhat restricted
 145 tough. Not all cases work as expected.
 146
 147 .. aafigure::
 148
 149                                      +
 150       |  -  +   |  -  +   |  -  +   /               -
 151      /  /  /   /  /  /   /  /  /   /     --     |/| /    +
 152     |  |  |   +  +  +   -  -  -   /     /  \        -   \|/  |\
 153                                  +     +    +          +-+-+ | +
 154     |  |  |   +  +  +   -  -  -   \     \  /        -   /|\  |/
 155      \  \  \   \  \  \   \  \  \   \     --     |\| \    +
 156       |  -  +   |  -  +   |  -  +   \               -
 157                                      +
 158
 159 And drawing longer diagonal lines with different angles looks ugly...
 160
 161 .. aafigure::
 162
 163     +      |
 164      \    /
 165       \  /
 166        --
 167
 168
 169 Arrows
 170 ------
 171 Arrow styles are::
 172
 173     --->   | | | | | |
 174     ---<   | | | | | |
 175     ---o   ^ V v o O #
 176     ---O
 177     ---#
 178
 179 .. aafigure::
 180
 181     --->   | | | | | |
 182     ---<   | | | | | |
 183     ---o   ^ V v o O #
 184     ---O
 185     ---#
 186
 187 Boxes
 188 -----
 189 Boxes are automatically draw when the edges are made with ``+``, filled
 190 boxes are made with ``X`` (must be at least two units high or wide).
 191 It is also possible to make rounded edges in two ways::
 192
 193     +-----+   XXX  /--\     --   |
 194     |     |   XXX  |  |    /    /
 195     +-----+   XXX  \--/   |   --
 196
 197 .. aafigure::
 198
 199     +-----+   XXX  /--\     --   |
 200     |     |   XXX  |  |    /    /
 201     +-----+   XXX  \--/   |   --
 202
 203 Fills
 204 -----
 205
 206 Upper case characters generate shapes with borders, lower case without border.
 207 Fills must be at least two characters wide or high. (This reduces the chance
 208 that it is detected as Fill instead of a string)
 209
 210 .. aafigure::
 211
 212     A   B   C   D   E   F   G   H   I   J   K   L   M
 213      AA  BB  CC  DD  EE  FF  GG  HH  II  JJ  KK  LL  MM
 214      AA  BB  CC  DD  EE  FF  GG  HH  II  JJ  KK  LL  MM
 215
 216      aa  bb  cc  dd  ee  ff  gg  hh  ii  jj  kk  ll  mm
 217      aa  bb  cc  dd  ee  ff  gg  hh  ii  jj  kk  ll  mm
 218
 219     N   O   P   Q   R   S   T   U   V   W   X   Y   Z
 220      NN  OO  PP  QQ  RR  SS  TT  UU  VV  WW  XX  YY  ZZ
 221      NN  OO  PP  QQ  RR  SS  TT  UU  VV  WW  XX  YY  ZZ
 222
 223      nn  oo  pp  qq  rr  ss  tt  uu  vv  ww  xx  yy  zz
 224      nn  oo  pp  qq  rr  ss  tt  uu  vv  ww  xx  yy  zz
 225
 226 Complex shapes can be filled:
 227
 228 .. aafigure::
 229
 230     CCCCC     C         dededede
 231      C  CCCC  CC        dededede
 232      CC    CCCCC        dededede
 233
 234 Text
 235 ----
 236 The images may contain text too. There are different styles to enter text:
 237
 238 *direct*
 239
 240 Bby default are repeated characters detected as fill::
 241
 242     Hello World  dd d
 243                     d
 244
 245 .. aafigure::
 246
 247     Hello World  dd d
 248                     d
 249
 250 *quoted*
 251
 252 Text between quotes has priority over any graphical meaning::
 253
 254     "Hello World"  dd d
 255                       d
 256
 257 .. aafigure::
 258
 259     "Hello World"  dd d
 260                       d
 261
 262 ``"``, ``'`` and ``\``` are all valid quotation marks. The quotes are not
 263 visible in the resulting image. This not only disables fills (see below), it
 264 also treats ``-``, ``|`` etc as text.
 265
 266 *textual option*
 267
 268 The ``:textual:`` option disables horizontal fill detection. Fills are only
 269 detected when they are vertically at least 2 characters high::
 270
 271     Hello World  dd d
 272                     d
 273
 274 .. aafigure::
 275     :textual:
 276
 277     Hello World  dd d
 278                     d
 279
 280
 281 Other
 282 -----
 283
 284 ::
 285
 286     * { }
 287
 288 .. aafigure::
 289
 290     * { }
 291
 292
 293
 294 TODO
 295 ====
 296
 297 - Symbol detection: scan for predefined shapes in the ASCII image
 298   and output them as symbol from a library
 299
 300 - Symbol libraries for UML, flowchart, electronic schematics, ...
 301
 302 - The way the image is embedded is a hack (inserting a tag trough a raw node...)
 303
 304 - Search for ways to bring in color. Ideas:
 305
 306     - have an :option: to set color tags. Shapes that touch such a tag
 307       inhertit it's color. The tag would be visible in the ASCII source tough::
 308
 309         .. aafigure::
 310             :colortag: 1:red, 2:blue
 311
 312             1--->  --->2
 313
 314     - ``:color: x,y,color`` but counting coordinates is no so fun
 315
 316     drawback: both are complex to implement, searching for shapes that belong
 317     together. It's also not always wanted that e.g. when a line touches a
 318     box, both have the same color
 319
 320 - aafigure probably needs arguments like ``font-family``, ...
 321
 322 - Punctuation not included in strings (now a bit improved but if it has a
 323   graphical meaning , then that is chooses, even if it makes no sense),
 324   underlines in strings are tricky to detect...
 325
 326 - Dotted lines? ``...``
 327
 328 - Group shapes that belong to an object, so that it's easier to import and
 329   change the graphics in a vector drawing program.
 330
 331 - Path optimizer, it happens that many small lines are output where a long
 332   line could be used.
 333
 334
 335 License
 336 =======
 337
 338 BSD
 339
 340 Tests
 341 =====
 342
 343 To compare input and output, look at the sources of this file_.
 344
 345 .. _file: README.txt
 346
 347
 348 Simple tests
 349 ------------
 350 Different arrow types:
 351
 352 .. aafigure::
 353
 354     <-->  >->   --> <--
 355     >--<  o-->  -->+<--
 356     o--o          o=>
 357
 358 Boxes and shapes:
 359
 360 .. aafigure::
 361
 362     +---------------+
 363     |A box with text|
 364     +---------------+
 365
 366 .. aafigure::
 367
 368         ---> | ^|   |   +++
 369         <--- | || --+-- +++
 370         <--> | |V   |   +++<-
 371      __             __    ^
 372     |  |__  +---+  |__|   |
 373             |box|   ..
 374             +---+  Xenophon
 375
 376
 377 Flow chart
 378 ----------
 379 .. aafigure::
 380     :textual:
 381
 382         /---------\
 383         |  Start  |
 384         \----+----/
 385              |
 386              V
 387         +----+----+
 388         |  Init   |
 389         +----+----+
 390              |
 391              +<-----------+
 392              |            |
 393              V            |
 394         +----+----+       |
 395         | Process |       |
 396         +----+----+       |
 397              |            |
 398              V            |
 399         +----+----+  yes  |
 400         |  more?  +-------+
 401         +----+----+
 402              | no
 403              V
 404         /----+----\
 405         |   End   |
 406         \---------/
 407
 408
 409 UML
 410 ---
 411 No not really, yet. But you get the idea.
 412
 413 .. aafigure::
 414     :scale: 0.8
 415
 416     +---------+  +---------+  +---------+
 417     |Object 1 |  |Object 2 |  |Object 3 |
 418     +----+----+  +----+----+  +----+----+
 419          |            |            |
 420          |            |            |
 421          X            |            |
 422          X----------->X            |
 423          X            X            |
 424          X<-----------X            |
 425          X            |            |
 426          X            |            |
 427          X------------------------>X
 428          |            |            X
 429          X----------->X            X---+
 430          X            X            X   |
 431          |            |            X<--+
 432          X<------------------------X
 433          X            |            |
 434          |            |            |
 435          |            |            |
 436
 437 .. aafigure::
 438     :scale: 0.8
 439
 440     +---------+         +---------+     +---------+
 441     |  Shape  |         |  Line   |     |  Point  |
 442     +---------+         +---------+   2 +---------+
 443     | draw    +<--------+ start   +----O+ x       |
 444     | move    +<-+      | end     |     | y       |
 445     +---------+   \     +---------+     +---------+
 446                    \
 447                     \   +---------+
 448                      +--+ Circle  |
 449                         +---------+
 450                         | center  |
 451                         | radius  |
 452                         +---------+
 453
 454 .. aafigure::
 455
 456                              /-----------\     yes /----------\
 457                           -->| then this |--->*--->| and this |
 458                       +  /   \-----------/    |no  \----------/
 459      /------------\   +--                     |
 460      | First this |-->+                       |
 461      \------------/   +--                     |
 462                       +  \   /---------\      V        /------\
 463                           -->| or that |----->*------->| Done |
 464                              \---------/               \------/
 465
 466 Electronics
 467 -----------
 468 It would be cool if it could display simple schematics.
 469
 470 .. aafigure::
 471     :fill: #fff
 472
 473           Iin +-----+      Iout
 474         O->---+ R1  +---o-->-----O
 475        |      +-----+   |         |
 476     Vin|       100k   ----- C1    | Vout
 477        |              ----- 100n  |
 478        v                |         v
 479         O---------------o--------O
 480
 481 .. - Resistor should not be filled -> can be solved by symbol detection
 482
 483 - Capacitor not good, would prefer ``--||--``  -> symbol detection
 484
 485
 486 .. aafigure::
 487
 488        |/|       |\|       | |     +---+       e|
 489     ---+ +---  --+ +--   --+ +--  -+   +-    b|/
 490        |\|       |/|       | |     +---+    --+
 491                                               |\
 492        |        |           |        |         c|
 493       -+-      -+-         -+-      +++
 494       / \      \ /                  | |    -   -
 495       -+-      -+-         -+-      | |    c\ /e
 496        |        |           |       +++     -+-
 497                                      |       |b
 498
 499 - Diodes OK
 500
 501 - Caps not optimal. Too far apart in image, not very good recognisable in
 502   ASCII. Space cannot be removed as the two ``+`` signs would be connected
 503   otherwise. The schematic below uses an other style.
 504
 505 - Arrows in transistor symbols can not be drawn
 506
 507 Here is a complete circuit with different parts:
 508
 509 .. aafigure::
 510     :fill: #fff
 511     :scale: 0.8
 512     :textual:
 513
 514                          Q1  _  8MHz
 515                            || ||
 516                       +----+| |+----+
 517                       |    ||_||    |
 518                       |             |
 519                 +-----+-------------+-----+
 520                 |    XIN           XOUT   |
 521                 |                         |
 522                 |                    P3.3 +--------------+
 523     SDA/I2C O---+ P2.0                    |              |
 524                 |                         |             e|
 525                 |        MSP430F123       |   +----+  b|/  V1
 526     SCL/I2C O---+ P2.1               P3.4 +---+ R1 +---+   PNP
 527                 |                         |   +----+   |\
 528                 |           IC1           |      1k     c|    +----+
 529                 |                         |              o----+ R3 +---O TXD/RS232
 530                 |    VCC             GND  |              |    +----+
 531                 +-----+---------------+---+              |      1k
 532                       |               |                  |    +----+
 533                       |               |                  +----+ R2 +---O RXD/RS232
 534                       |               |                       +----+
 535                       |               |                         10k
 536     GND/I2C O---o-----+----o----------o-----------o--------------------O GND/RS232
 537                 |     |    |   C1     |           |   C2
 538                =+=    |  ----- 1u     |         ----- 10u
 539                       |  ----- 5V +---+---+     ----- 16V
 540                       |    |      |  GND  |       |            D1|/|
 541                       +----o------+out  in+-------o----------o---+ +---O RTS/RS232
 542                                   |  3V   |                  |   |\|
 543                                   +-------+                  |
 544                                    IC2                       | D2|/|
 545                                                              +---+ +---O DTR/RS232
 546                                                                  |\|
 547
 548
 549 Timing diagrams
 550 ---------------
 551 .. aafigure::
 552     :aspect: 0.5
 553
 554       ^    ___     ___           ____
 555     A |___|   |___|   |_________|    |______
 556       |      ___        ___           __
 557     B |_____|   |______|   |________XX  XX__
 558       |
 559       +-------------------------------------> t
 560
 561 Here is one with descriptions:
 562
 563 .. aafigure::
 564
 565                         SDA edge
 566          start                              stop
 567            |    |          |                 |
 568            v    v          v                 v
 569         ___      __________                   ___
 570     SDA    |    |          |                 |
 571            |____|          |_____..._________|
 572         ______      _____       _..._       _____
 573     SCL       |    |     |     |     |     |
 574               |____|     |_____|     |_____|
 575
 576               ^    ^     ^     ^     ^     ^
 577               |    |     |     |     |     |
 578               | 'sh_in'  |  'sh_in'  |  'sh_in
 579            'sh_out'   'sh_out'    'sh_out'
 580
 581                         SCL edge
 582
 583 Statistical diagrams
 584 --------------------
 585
 586 Benfords_ distribution of the sizes of files on my hard drive:
 587
 588 .. _Benfords: http://en.wikipedia.org/wiki/Benfords_law
 589
 590 .. aafigure::
 591     :name: benford
 592     :foreground: #ff1050
 593     :aspect: 0.7
 594
 595       |
 596     1 +------------------------------------------------------------> 31.59%
 597     2 +-------------------------------> 16.80%
 598     3 +-----------------------> 12.40%
 599     4 +-----------------> 9.31%
 600     5 +--------------> 7.89%
 601     6 +-----------> 6.10%
 602     7 +---------> 5.20%
 603     8 +---------> 4.90%
 604     9 +--------> 4.53%
 605       |         +         |         +         |         +         |
 606       +---------+---------+---------+---------+---------+---------+--->
 607       |         +         |         +         |         +         |
 608       0         5        10        15        20        25        30
 609
 610 Just some bars:
 611
 612 .. aafigure::
 613     :fill: #00b
 614
 615     ^     2
 616     |    EE
 617     | 1  EE       4
 618     |DD  EE   3  HH
 619     |DD  EE  GG  HH
 620     |DD  EE  GG  HH
 621     +------------------>
 622
 623
 624 Schedules
 625 ---------
 626
 627 .. aafigure::
 628
 629     "Week"      |  1    |  2    |  3    |  4    |  5    |
 630     ------------+----------------------------------------
 631     "Task 1"    |HHHH
 632     "Task 2"    |    EEEEEEEEEEEE
 633     "Task 3"    |                GGGGGGGGZZZZZZZZZZ
 634     "Task 4"    |DD      DD          DD          DD