Shaky: ASCII Diagram to PNG | Hacker News Reader

Shaky: ASCII Diagram to PNG

shaky.github.bushong.net

272 pointstambourine_man70 comments

I use this tool almost every day turning sequence diagrams into drawings. https://www.websequencediagrams.com While the "back of a napkin"style is hip, management seems to prefer cleaner drawings. I'd use shakey, if it made "professional" drawings.

That looks like it's using Dot notation: https://en.wikipedia.org/wiki/DOT_%28graph_description_langu...

I like to use http://www.graphviz.org/ to convert from DOT to PNG.

Uhm, if the only thing you base that assumption on is the use of -> to mark a line with an arrowhead ... sure. But it's pretty far from dot, actually.

They are similar in that they are both languges that can be used to specify diagrams.

dot describes graphs. Sequence diagrams aren't really graphs in my book.

PlantUML does the same thing also.

Yeah, PlantUML is really an awesome tool. Also has an online editor: http://www.planttext.com/planttext

Not the greatest samples on there though - better resources on http://plantuml.com/.

You can use the &s param (or the dropdown..) to change the style of the image created by websequencediagrams.

&s=napkin for yourself.

&s=omegapple for management.

From a quick look at the code for Shaky, getting "cleaner" drawings would only require replacing 2 functions (shakyLine and bulb). In "bulb" it'd just require removing one line and changing one. In shakyLine you'd need to strip out most of it and replace it with a 1-2 line version.

http://yuml.me can do simple diagrams too

These ideas always seem to top HN. They are cute, but interactive diagram editors have been around a while and, unfortunately, are just faster to use and are more flexible.

Maybe it'd make more sense to just have one of these tools implement export to ACSII?

> interactive diagram editors have been around a while and, unfortunately, are just faster to use and are more flexible

Agreed. I think what is more helpful is taking a shorthand version of a diagram and generate it into a graph (flowchart.js is an example of this).

I think the appeal would be that, since it's text based, it's already supported by git/mercurial/svn/name-your-vcs. A binary format would need some sort of history/diff support inside it to work well with a specific plugin for s VCS. An XML-based format would integrate well with a VCS, but you lose the clarity of the ASCII based diagrams.

It may seem "cute" or "toyish", but I woudl try to use it before giving an opinion. I certainly did that with markdown and ended up moving a lot of docs to that format, right in the repos with the code.

"since it's text based, it's already supported by git/mercurial/svn/name-your-vcs"

But doesn't that still apply if you had a visual tool exporting to ASCII? It'd save you the difficulty of moving sections around in a text editor, but give you the visual diff.

Now you then need to cut and paste back and forth from your documents in order to edit them.

Not if you import that format as well, that's not impossible to implement.

If you come up with a tool that will pick up on a diagram in a readable ascii format in the middle of a document, let me edit it, and then patch in the updated diagram without making any kind of changes to other portions of the file, then we'd be getting somewhere.

Even then there'd be issues, as e.g. I might want to modify descriptions elsewhere in the file in between modifying the diagram. As a concrete example, I am doing that these days with a spec for a system I'm planning. I'm using a custom Markdown based processor with a filter that takes Graphviz/dot syntax inline, and while I edit the diagram, I'll also then often want to write something about what I've added to it. So if I was going to use an external program, the roundtrip from text editor -> diagram editor -> text editor would need to be very fast and smooth.

Though to be really useful for me, it'd need to work for me via an ssh connection as well...

It's really hard to beat plain text for some of these use-cases. At least without first getting more graphics capabilities back into our terminals.

No, "supported by git" means that if I edit the diagram and check it in, and you also edit the diagram and check it in, Git can usually merge the changes automatically if they don't conflict; and if they do conflict, it can give us a version of the file that contains both changes, with the conflict marked, and makes it pretty easy to produce a merged version.

If your visual tool merely exports to ASCII, this won't work. If it stores its data in ASCII, it might. But it needs to be more than just "doesn't use control characters and non-7-bit characters" — it needs to have reasonably short lines that mostly don't reoccur and whose position, if meaningful at all, is meaningful only relative to the position of other nearby things, rather than by absolute line number or byte position or something.

This. I would love, as an author and teacher, to keep my flowcharts, diagrams, etc with my book code.

Right now I'm using SVG for that, but it's kinda rotten.

Is that same problem, i.e. you want to be able to diff your diagrams or do you want the actual data format embedded in your document.

If it's the second, you can embed XML within SVG or a PNG. If you draw something simple in draw.io [0] (which I do co-author) and then "File->Export As" either "SVG with XML" or "PNG with XML" the diagram data is stored within the display format itself. This way you can just reload the SVG+XML or PNG+XML and carry on editing. But the PNG and SVG display as you'd normally expect.

Does that solve your problem?

[0] https://www.draw.io/?splash=0

Yeah, I feel this pain too. MJD's Linogram might work. I've also tried writing the diagrams as Python to produce SVG, or in D3 (to produce SVG), which both work reasonably well but seem like a lot of work.

I use draw.io, and export to xml.

It should be easy to do flowcharts in pic(1). It's also more diff-friendly.

GNU pic can target LaTeX directly, if that helps.

SVG/GraphML are text based too

SVG cannot be entered by humans in the same way this can

I don't agree. SVG is very human-editable indeed. It's easier than even PostScript or OpenGL.

To each his own then I guess. Some may enjoy aligning pipe symbols and pluses, I don't.

I don't either, but I enjoy cutting and pasting back and forth, or keeping diagrams in separate formats, or trying to write SVG manually even less.

It is also supported in your text editor.

Agreed. This could be very useful if leveraged into a Wiki-plugin.

Try removing one of the left boxes (not exactly easy in this format) and then view the git diff. Think about trying to fix a conflict with that!

Indeed, side-by-side boxes editing/merging would be messy! But it still looks that something that could be integrated into a reasonably organized repository. Not the best of tools, but better than the alternative?

> They are cute, but interactive diagram editors have been around a while and, unfortunately, are just faster to use and are more flexible.

Personally, I build most of my diagrams in either graphviz or LaTeX/TikZ. Graphviz constructs certain types of diagrams very quickly, as long as you don't care deeply about precise placement and layout. And TikZ integrates perfectly with LaTeX documents, and makes complex diagrams and graphs more manageable and scriptable.

I've had a need in the past to put small diagrams like this into source code comments. Having an ASCII form for them is really useful. I have used ditaa in the past but this one looks good too.

I'd rather use a visual editor, but I've repeatedly turned to text-based diagram markup (mostly PlantUML) because I found the interactive tools to be painful to use. In most visual editors adding a new node takes lots of of mouse motions. In PlantUML it's pretty much just adding a line.

Ideally I want a visual editor with an abstract understanding of what you can do in diagrams, a keyboard driven interface and automation of a good first approximation of what I want, giving me the ability to tweak the resulting layout.

Drawing diagrams on a piece of paper or a whiteboard beats both approaches handily. Which is pretty sad.

I wrote the original code (not this CoffeeScript port) so that I could create simple diagrams fast without resorting much to dragging stuff around with mouse. If you want to create a sequence of diagrams where each next one is just slightly different from the previous one then textual approach is simply superior to point-and-click style editing. Other parts of my motivation were outlined here[1].

Having this ASCII -> image converter also allows me to embed diagrams into blogposts as text without actually making images out of them. See [2] as an example of such embedding.

[1] http://mrale.ph/blog/2012/11/25/shaky-diagramming.html [2] http://mrale.ph/blog/2014/07/30/constructor-vs-objectcreate....

This works very well with diagrams created using http://asciiflow.com/

Just tried it out and the export->copy->paste->save worked really, really well.

Is a great service, but I'd love to have something I can use locally. A _lot_ of my time diagramming is spent disconnected, transitioning over photos of whiteboards to actual diagrams.

Are you aware of anything that is a local client?

Have you tried artist-mode in emacs?

asciio has layers, which is orders more powerful

There is years ago asciio, works well on linux environments, some distros have it already packaged, otherwise you can pull it from CPAN.

Looks something like this: http://wiki.cornempire.net/_media/asciiart/diagram1.png

Asciio should be available as a package. For example, in Debian, it can be installed:

    sudo apt-get install asciio

This visual editor allows you to easily draw the ASCII diagrams to begin with (for placing in code):

http://asciiflow.com/

ditaa makes some much nicer diagrams: http://ditaa.sourceforge.net/

Also, org-mode has native support for it!

I like Shaky's rough style better

Matter of taste I suppose, but I find the rought style almost as irritating as ASCII diagrams themselves. Both involve a lot of visual noise which is a huge distraction from the semantic content, for me. With something like Shaky, the combination of handwritten-looking text but the perfect consistency of computer fonts just creates an 'uncanny valley' scenario where my focus is drawn to the artificiality of the textural qualities - like bad CG in an old or low-budget film - rather than the assimilating the basic shapes and relationships that they are meant to present.

When I see something like this part of me always silently wonders 'if you think these handwritten-style fonts are so cool, why didn't you write your whole Readme in the same font? Probably because deep down, you know it's actually hard to read, so why make your diagrams hard to read?'

Ah, love it! I've taken to primarily doing ASCII figures when I write papers or other things. This along with Monodraw[0] will make a nice suite of tools! (absolutely love the shaky lines, reminds me of XKCD style)

[0] http://monodraw.helftone.com/

https://github.com/dbushong/shaky (last touched by the author 3 years ago)

My impression is most people don't know about graphviz and dot, and implement these sorts of tools to fill this (admittedly big) gap.

Graphviz is great if you either want to automatically generate diagrams of huge graphs, or if you care more about structure than appearance.

But creating pretty diagrams with Graphviz/dot is an exercise in pain.

I love seeing more of these tools, and plan to integrate several of them in the scripts I use to build my blog, not to supplant the cases where I use Graphviz, but to augment them for the many situations where I want to do diagrams that need more precise control than Graphviz does.

(My personal Graphviz self-flagellation exercise involves an XSL file to convert the SVG output from dot to something prettier: https://github.com/vidarh/diagram-tools )

But creating pretty diagrams with Graphviz/dot is an exercise in pain.

I think Graphviz really needs a better routing algorithm - with many vertices and edges the result starts looking like a mass of tangled hair. Something closer to the routing algorithms used in PCB design[1] would be far more readable.

[1] https://en.wikipedia.org/wiki/Routing_(electronic_design_aut...

"My personal Graphviz self-flagellation"

I can beat that - I had an ASP.Net application that queried a set of SharePoint lists to generate 100s of diagrams giving details of what applications were used for different business processes at each site in a large multinational.

It did work but there was a lot of tweaking of the process to create the dot files....

I use Mermaid [1]. It has similar layout algorithms as Graphiviz/dot, and is significantly prettier out of the box.

Mermaid has multiple renderers (including a client-side JavaScript one), including SVG, so you can trivially style all your diagrams using CSS. It can also process diagrams embedded in Markdown.

That said, just like Graphviz, its weak points is "messy" diagrams. But it supports subgraphs, which can help making them cleaner.

[1] https://github.com/knsv/mermaid

Uh, I'm pretty sure David knows about graphviz. (You said "graphviz and dot", suggesting that you don't know that dot is one of the programs in graphviz.)

I tried it with

    +-----+-----+  +-----+-----+
    |     |     |  |     |    /|
    |     |     |  |     |   / |
    |  *  |  *--+--+> *  |  /  |
    |  |  |     |  |  |  | /   |
    |  |  |     |  |  |  |/    |
    +--+--+-----+  +--+--+-----+
       |              |
       |              |
       v              v

      foo            bar

Close, just needs a little work. Also, is there any way to get a permalink to some specific diagram?

A non-shaky mode would be great too.

The 'drawn' -style output is cute. Would be nice if there were dot renderers that did 'artistic' renderings of diagrams.

Dot has a SVG output mode that's reasonably easy to tweak/manipulate. I did an XSL file that adds gradients and drop-shadows to the Dot output back in the day [1] and there are a number of annoying corner cases to deal with, but it's not too horrible; would've been easier in something other than XSL though.

[1] https://github.com/vidarh/diagram-tools

Very nice! I've used little .ps icon files before, and been generally unhappy with the whole thing.

At its heart, graphviz is great. But the tools so need a nice little modernizing.

At the basic level, I found myself being very repetitive because its not possible for graphviz nodes to inherit attributes from others etc. No CSS kind of hierarchy.

That is pretty awesome!

I only found two bugs:

1) if you type just something small, like "asdf", it doesn't render. It seems to require you to start with a long horizontal line to make it properly calculate the width.

2) this one is understandable, but, if you want to write code that decrements something, e.g. x--, it renders the -- as horizontal line instead.

Is it just me or the ASCII diagrom looks way better than the generated faux-comic-PNG?

There's also aafigure: https://pythonhosted.org/aafigure/

It would be great if there is a some kind of tool with predefined objects like the square, table, start and so on. So you can easily added to your text

Doesn't work for me. I click the button and I get a blank PNG.

Edit: Oh, you have to edit the field for it to actually render it, okay. That wasn't obvious.

It's like turning a painting back into a sketch, or maybe not. I'm confused... which comes first? ascii or sketch?

It should have support for emoticons.

Agreed.

Neat. Could really do with supporting diagonal lines / \

Yeah. This bit me on the first ascii diagram of mine I tried it on. But other than that, very neat.

Reply on news.ycombinator.com