Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/asciitosvg/asciitosvg

Create beautiful SVG renderings of ASCII diagrams.
https://github.com/asciitosvg/asciitosvg

ascii-art asciitosvg beautiful-svg-diagrams diagrams markdown-extension svg

Last synced: 5 days ago
JSON representation

Create beautiful SVG renderings of ASCII diagrams.

Awesome Lists containing this project

README 

        
# ASCIIToSVG



    .-------------------------.

    |                         |

    | .---.-. .-----. .-----. |

    | | .-. | +-->  | |  <--| |

    | | '-' | |  <--| +-->  | |

    | '---'-' '-----' '-----' |

    |  ascii     2      svg   |

    |                         |

    '-------------------------'



   https://github.com/asciitosvg



Create beautiful SVG diagrams from ASCII art.



## Introduction



### License



ASCIIToSVG is copyright © 2012-2018 The ASCIIToSVG contributors, and is

distributed under an MIT license. All code without explicit copyright retains

this license. Any code not adhering to this license is explicit in its own

copyright.



### What does it do?



ASCIIToSVG is a pretty simple Go library (with an accompanying CLI tool) that

parses ASCII art diagrams, attempting to convert them to an aesthetically

pleasing SVG output. Someone snidely remarked in a HN thread that if you make

a thing that generates visual output, show some examples of that output. Ask

GitHub to support insertion of SVG into their Markdown. In the meantime, you

can easily get example output by running `a2s -L`.



### What about that other project?



The original code at https://github.com/dhobsd/asciitosvg suffers from a

number of issues. It isn't particularly efficient in what's effectively a graph

search problem, and its implementation in PHP leaves a bit to be desired. Some

side-effects of this are that things one would really expect (like using `+`

for angled polygon corners) are not supported. This project subsumes the other,

which will eventually become unmaintained. Another advantage to the Go version

is that it supports UTF-8 inputs natively. Other features, like tab expansion,

have also been introduced.



Some other features, like custom objects, have not yet been implemented.



### So... why did you do this?



There are a few reasons:



 * We feel that Markdown is a great format for authoring documents.

 * When authoring technical documents, it's common to want to embed diagrams.

 * People say pictures are worth a thousand words.



Markdown support for inline images isn't particularly great, because you

cannot view the image in text mode. An ASCII diagram is usually doable for

many illustrations, but is often rendered as text in the HTML output. We'd

like the best of both worlds.



### Aren't there already things that do this?



Well, yes. There is a project called [ditaa][1] that has some of this

functionality. When dhobsd initially implemented A2S, ditaa left a couple key

points to be desired:



 * Its annotation format was too verbose, distracting from the visual content

 in text mode.

 * Its output was a rasterized format, so it didn't scale well.



Later, ditaa became unusable. The [software it was integrated with][2] was

written in PHP, and had to shell out to run ditaa. Because ditaa was written in

Java, new JVMs were spawned often to provide real-time feedback on diagram

changes. The functionality was re-implemented in PHP to output SVG, but this

ultimately ran into the issues described above. Hence this project.



## Compilation and Usage



To get the CLI tool, make sure `$GOPATH/bin` is in your `$PATH`. Run:



    $ go get github.com/asciitosvg/asciitosvg/cmd/a2s

    $ a2s -h

     .-------------------------.

     |                         |

     | .---.-. .-----. .-----. |

     | | .-. | +-->  | |  <--| |

     | | '-' | |  <--| +-->  | |

     | '---'-' '-----' '-----' |

     |  ascii     2      svg   |

     |                         |

     '-------------------------'



    https://github.com/asciitosvg



    [1,0]: {"fill":"#88d","a2s:delref":1}



    Usage of go/bin/a2s:

      -L	Generate SVG of the a2s logo.

      -b	Disable drop-shadow blur.

      -f string

            Font family to use. (default "Consolas,Monaco,Anonymous Pro,Anonymous,Bitstream Sans Mono,monospace")

      -i string

            Path to input text file. If set to "-" (hyphen), stdin is used. (default "-")

      -o string

            Path to output SVG file. If set to "-" (hyphen), stdout is used. (default "-")

      -t int

            Tab width. (default 8)

      -x int

            X grid scale in pixels. (default 9)

      -y int

            Y grid scale in pixels. (default 16)



To play with the library:



    $ go get github.com/asciitosvg/asciitosvg



Documentation on the API is available through your local `godoc` server.



## Drawing diagrams



Enough yammering about the impetus, code, and functionality. I bet you want

to draw something. ASCIIToSVG supports a few different ways to do that. 



### Basics: polygons and line segments



ASCIIToSVG supports concave and convex polygons with rounded or

degree-appropriate corners. Horizontal, vertical, and diagonal lines are all

supported. ASCIIToSVG has nearly complete support for output from

[App::Asciiio][3]. Edges of polygons and line segments can be drawn using the

following characters:



 * `-` or `=`: Horizontal lines, solid or dashed (respectively).

 * `|` or `:`: Vertical lines, solid or dashed (respectively).

 * `\` or `/`: Diagonal lines.

 * `+`: Edge of a line segment, or an angled corner.



Ticks and dots can be added into the middle of a line segment using `x` and

`o`, respectively. Note that these characters cannot be inserted into diagonal

lines, and they cannot begin a line.



To draw a polygon or turn a line, corners are necessary. The following

characters are valid corner characters:



 * `'` and `.`: Quadratic Bézier corners

 * `+`: Angled corners.



The `+` token is a control point for lines. It denotes an area where a line

intersects another line or traverses a box boundary.



A simple box with 3 rounded corners and a line pointing at it:



    +----------.

    |          | <---------

    '----------'



Diagonals may be used to form a closed polygon, but this is rarely a good idea.



### Basics: markers



Markers can be attached at the end of a line to give it a nice arrow by

using one of the following characters:



 * `<`: Left marker

 * `>`: Right marker

 * `^`: Up marker

 * `v`: Down marker



### Basics: text



Text can be inserted at almost any point in the image. Text is rendered in

a monospaced font. There aren't many restrictions, but obviously anything

you type that looks like it's actually a line or a box is going to be a good

candidate for turning into some pretty SVG path. Here is a box with some

plain black text in it:



    .-------------------------------------.

    | Hello here and there and everywhere |

    '-------------------------------------'



### Basics: formatting



It's possible to change the format of any boxes / polygons you create. This

is done (true to markdown form) by providing a reference on the top left

edge of the object, and defining that reference at the bottom of the input.

References *must* appear in the input *below* the objects they are associated

with, and preferably at the bottom of the diagram.



An example:



    .-------------.  .--------------.

    |[Red Box]    |  |[Blue Box]    |

    '-------------'  '--------------'



    [Red Box]: {"fill":"#aa4444"}

    [Blue Box]: {"fill":"#ccccff"}



Text appearing within a stylized box automatically tries to fix the color

contrast if the black text would be too dark on the background. The

reference commands can take any valid SVG properties / settings for a

[path element][4]. The commands are specified in JSON form, one per line.

Reference commands do not accept nested JSON objects -- don't try to

place additional curly braces inside! (Indeed, the current Go implementation

currently requires all JSON values other than `a2s:delref` to be strings.)



By default, the text of a reference is rendered inside the polygon, and the

reference is left in-tact in the output. You can remove the reference text

using the `a2s:delref` option; if it is set to any valid JSON value, it will

remove the reference text. You can use the `a2s:label` to replace the text with

any value, or to an empty string to remove it entirely.



The `a2s:link` option will wrap the target object with a clickable link to the

URL specified in the value.



#### Special references



It is possible to reference an object for formatting using its X and Y

coordinates. The coordinate system for ASCIIToSVG starts at (0, 0) in the top

left of the diagram.



Such references should only be made for stable diagrams, and only if you

*really* need to style text or a line in some particular way. These references

are marked by beginning the line with `[X,Y]` where `X` is the numeric row and 

`Y` is the numeric column of the object's top-left-most point.



## Unsupported features



The Go implementation does not yet support all the features of the PHP version.

Features that are currently unimplemented include:



 * Custom objects, including the `a2s:type` format specifier, are not yet

 implemented.

 * No support is planned for angled corners using `#`.

 * No support is planned for undirected lines using `*`.



## External Resources



There are some interesting sites that you might be interested in; these are

mildly related to the goals of ASCIIToSVG:



 * [ditaa][1] (previously mentioned) is a Java utility with a very similar

   syntax that translates ASCII diagrams into PNG files.

 * [App::Asciio][3] (previously mentioned) allows you to programmatically

   draw ASCII diagrams.

 * [Asciiflow][5] is a web front-end to designing ASCII flowcharts.



If you have something really cool that is related to ASCIIToSVG, and I have

failed to list it here, do please let me know.



[1]: http://ditaa.sourceforge.net/ "ditaa - DIagrams Through ASCII Art"

[2]: http://mtrack.wezfurlong.org/ "mtrack project management software"

[3]: http://search.cpan.org/dist/App-Asciio/lib/App/Asciio.pm "App::Asciio"

[4]: http://www.w3.org/TR/SVG/paths.html "SVG Paths"

[5]: http://www.asciiflow.com/ "Asciiflow"