Hacker News Reader

The main advantage I see is that the markdown diagram is understandable in plaintext. That's quite a powerful idea because you don't need to understand any intermediate language. Graphviz and mermaid are interpretable, but not in an immediately visual way.

I would be interested in a solution that can take graphviz files and output markdown-friendly diagrams, which can then be compiled back into vector diagrams.

Perl to the rescue!

https://codeyarns.com/2017/10/21/how-to-convert-dot-graph-to...

We could also use a higher-bandwidth format than plain text? There is a lot of technical content which could be improved greatly by easy graphical tools for diagrams, equations, and so on, which is going a bit by the wayside because of the all-in-on-plaintext attitude. I think there is a lot of opportunity for clearer communication being totally passed over because of our collective inertia with respect to making better tools which would allow this kind of thing.

The usual difficulty with moving beyond plain text is diffing/patching. Text has battle tested and decent visualisations for viewing the delta between two versions. Other formats generally don't.

How do you visualise the diff of a diagram? How do you integrate it with git? That seems hard.

It’s a fair point, but again I think that it’s a very small price to pay for the improved communication. Things do seem hard, but we solve very hard problems in programming all the time (or so it seems), except when it comes to our tools. Plain text is still king when it comes to code because it is so easy to diff (which I think is a good choice), but how about my silly comments explaining how a system works rather than just drawing it and embedding that in a comment? I think there is a lot of potential there.

visualizing the diff of an ascii-art diagram leaves a lot to be desired as well. addding an extra box or re-routing an arrow in the diagram on the markdeep homepage would produce a very messy diff. if you want good diffs for highly visual content, converting that content to ascii art doesn't seem like the right answer to me.

the "magic" of this would also make me uncomfortable. if i draw a diagram and the rendered output doesn't look the way i want it, i wouldn't know how to fix it.

I kind of want the opposite of this: A GUI tool I can draw some diagram stuff out in that renders down to ASCII art.

Bonus points if it renders to Markdeep (or an equivalent) to be re-rendered as SVGs or whatever later on.

Edit: Here we go - http://asciiflow.com/

http://asciiflow.com/

This is cool, but could benefit from some figlet-like text options

There's also https://monodraw.helftone.com that lets you draw directly in ASCII.

Well actually that's more like Unicode Art ;)

Of course it's Mac only. :(

I like it when these use actual box-drawing characters, ie https://en.wikipedia.org/wiki/Box-drawing_character or https://en.wikipedia.org/wiki/Code_page_437.

Boxes made out of asterisks, dashes, and slashes appeal to me about as much as cutlery made out of recycled tin cans and coat hangers; it's the worst of both worlds, too ugly to qualify as real graphics and too distracting to be useful as text. Weirdly, the look worse than 'graphics' on the Commodore PET or TRS-80 (whose 'graphic' characters were helpfully printed on the keys and accessible through combination button presses).

Wow, I can't believe I went this long without realizing there were these characters specifically intended to be used in text based interfaces. It's funny, these are almost like the opposite of emojis, text trying to be graphics, rather than graphics trying to be text.

I remember playing with those ansí box characters back in the late 1990s... shit norton , microsoft and every other "graphical" ui for DOS used it.

I like to use the vim plugin DrawIt for ascii diagrams:

https://www.thegeekstuff.com/2009/12/how-to-create-ascii-dra...

https://github.com/vim-scripts/DrawIt

Pretty easy to create comments for code that need a drawing for clear expositions.

I actually like using ascii diagrams for relatively simple graphs, because I can incorporate them directly in my source code comments. Recently I even made a simple web page where you can create easily ascii diagrams using dot [0]

[0] https://dot-to-ascii.ggerganov.com/

For simple graph diagrams it's easy enough to open up a separate graphviz .dot file, write up a graph specification, run it through dot or neato, and include the .png in your markdown file. And then automate this with a Makefile.

Sounds interesting, would you mind sharing your workflow and your makefile? I tried graphviz ages ago and think it's a powerful and underused tool.

AsciiDoctor has GraphViz (and PlantUML plus a few more) available inline (it handles the conversion for you). The syntax has a few differences to Markdown but it's not too hard to adapt plus it has a few other awesome features that I always miss when in Markdown.

thanks

Sure! I use pandoc to render Markdown, but you can use whatever Markdown processor you like in place of pandoc.

Makefile

    all: example.html

    example.html: example.md example.png
        pandoc $< -o $@

    example.png: example.dot
        dot -Tpng $< -o $@

example.dot

    digraph G {
        foo -> bar;
    }

example.md

    # Example

    ![example graph](example.png)

thanks a lot!

> For simple graph diagrams it's easy enough to open up a separate graphviz .dot file, write up a graph specification, run it through dot or neato, and include the .png in your markdown file. And then automate this with a Makefile.

Or just use zim ( https://zim-wiki.org/ ) which allows you to embed graphviz diagrams in any 'page', and many other features.

> Does anyone go, hey, you know what would make my note-taking or web design faster and easier? Spending 20 minutes making an ascii art diagram instead of slapping the same three figures out in powerpoint in 20 seconds.

Yes, I do. I spend my time in a terminal all day and ASCII art is way more useful than an image reference which will never be able to load.

Show me a tool to export that powerpoint to ASCII and I'll be happy.

There's no reason images can't be displayed in terminals other "that's not how terminals work" historical baggage.

iTerm2, as one example, can display images just fine.

If I wanted images in my text I would use Code.

Images are fine as long as they don't fuck with line counts or column counts.

Diagrams with PlantUML in AsciiDoc are quite efficient. Faster than powerpoint.

I've included plantuml stuff in our internal documentation at work for a long time, and have got a lot of complements from people on how great our documentation is. I attribute a lot of this to the diagrams (mostly component and sequence diagrams), many of which are there just because of how simple and fast it is to create+maintain them with inline plantuml.

Benefits:

Fairly easy to learn syntax, and powerful enough for most technical documentation needs.

Easy to edit, easy to consume. No launching some heavy desktop app, no worrying about keeping PNG+source files up to date. (I do often use liveuml.com for editing any non-trivial diagrams though.)

Works with version control

Consistent style even when different people are working on diagrams

Drawbacks:

Not that pretty. Someone even mildly proficient at PowerPoint can make better-looking diagrams (though it takes longer). If you're doing internal or technical docs this isn't worth it, but for marketing/end-user facing stuff, maybe. I'll often just give my plantuml diagram to marketing and let them have a graphic designer pretty it up.

Less intuitive. The learning curve is a bit of a barrier for people that have spent years doing stuff in PowerPoint, and haven't yet bought into the other benefits. Especially for a simple diagram, it's hard to convince them to spend a couple hours so they can learn how to build it in 5-10 minutes with plantuml, vs just spending 10 minutes in PowerPoint. I think this is exacerbated by the fact a lot of the benefits come later when trying to edit and it gets more complex.

PlantUML syntax is also a lot easier to maintain and update than an ascii chart which is basically a low res pixel art.

Have you run into this?

https://github.com/asciidoctor/asciidoctor/issues/1087

I love all the features of asciidoc but it bothers me they can't get the actual HTML generation right.

In my opinion it's way better to have things all in one program. The clumsiness of needing to open up a heavyweight program like Powerpoint to then copy and paste the figure somehow into your document every time you revise is very annoying to me. Plus it's less portable.

This is why Microsoft invented OLE many decades ago. Admittedly it was a clunky, heavy and proprietary solution just like most other tech out of that company.

XML (via svg) can potentially be great for that... it saves the "what" so we only need software that does something useful with it.

> There's absolutely no workflow I can think of that is improved by my sitting there and trying to ASCII Art my way into a diagram. Does anyone go, hey, you know what would make my note-taking or web design faster and easier?

Documentation embedded in code docstrings. Yes, I could link to an external SVG but if you did that it wouldn't look great if I have to query the documentation via REPL.

I agree, but maybe it’s syntax. MermaidJS has pretty quick and easy syntax that makes whipping up diagrams simple enough for me to convert.

I'd be pretty happy with the ability to do inline graphviz diagrams. If I'm using Markdown then I'm not really after super great presentation quality, so not having a lot of control over layout doesn't necessarily bother me as long as I can describe the graph quickly.

I think I kind of like how this thing lets you do either quick ASCII art diagrams or embed graphviz (via Gravizo). The syntax for inserting Gravizo diagrams isn't too bad:

  ![Figure [graph]: A more complex graph example](http://g.gravizo.com/svg?
    digraph G {
     main -> parse -> execute;
     main -> init;
     main -> cleanup;
     execute -> make_string;
     execute -> printf
     init -> make_string;
     main -> printf;
     execute -> compare;
    })

An alternative to both I like is the blockdiag programs, including seqdiag, netdiag, and rackdiag. Diagrams as text that can be properly automated.

neat, thanks

http://blockdiag.com/en/nwdiag/index.html

Yeah, I thought the same when looking at this. Text editing my way to ASCII diagrams is time consuming and brings little value for my time.

The worst part isn't that it's time consuming but simple changes often require you to redraw the whole thing again. So for the most part a simple mermaid or graphviz is much more appropriate.

> If I need graphic charts/diagrams, I've already passed the markdown stage.

I disagree. Linux kernel documentation and many manpages contain ascii diagrams that proved extremity useful for helping me understanding the them.

I really hope to see diagrams adopted into the markdown standard (CommonMark).

Yeah ASCII Art is not ideal for drawings like this. I get frustrated enough at work writing comments requiring drawings. I can’t imagine trying to do that here.

Maybe something very simple: A->B<-C similar to the syntax described for causal diagrams in Judea Pearl’s “The Book of Why”

Plaintext gives you straightforward integration with git though, which is waaaay better than the built-in collaborative version control you have in MS Office.

An alternative to both I like is the blockdiag programs, including seqdiag, netdiag, and netdiag. Diagrams as text that can be properly automated.

ASCII diagrams aren't competing with powerpoint, diagrams made with sequence js, mermaid js, etc. are.

For the particular offerings of these libraries, a higher quality, professional looking output is generated in a shorter time than powerpoint.

And most importantly, one can version control it, as the source is plain text

> But there is a point where using a simple and elegant tool stops being simple and elegant - it can only be tortured so far outside its intended use-case before it stops being useful.

An alternative tool I've begun to like is TeXMe: https://github.com/susam/texme. It is like Markdeep but minimal--does not support any fancy features. Just plain Markdown and Latex. Very useful for note taking in a file that can publish itself. I don't think I can draw fancy diagrams while taking notes live so I don't need diagrams. So this simple tool serves me well.

TeX doesn't preclude diagrams. I use TikZ extensively, and I've found it much easier than any graphical diagram tool I've ever used. (As with most of TeX, it has a learning curve, but then a much easier steady-state after that learning curve.)