10 ms·

Show HN: Typograms, Markdown-like renderer for ASCII diagrams

140 points by sgoto 4y ago

einpoklum 4y ago
I like this, but - in what contexts will typograms be accepted and rendered? For example, email clients (e.g. Thunderbird) have not even bothered to let us use markdown for email. flowed-format text is about the most you can get out of them for now.
howto1312 4y ago
wentin 4y ago
This is very slick! Regard to editability of text diagram, brainstorming here: it would be cool to have two-way convertibility between text diagram and svg diagram. so users can use drag and drop like interaction to edit the svg diagram, and convert back to text diagram, so it has the best of both worlds. I guess roughly this idea already exists — there is program that converts image to ascii, but it lacks precision, as in the ascii to svg and then back to ascii would yield to different set from the starting point.
sgoto 4y ago
FWIW, I explained a bit why/how I've been using it here: https://twitter.com/samuelgoto/status/1548845628171722752 https://twitter.com/samuelgoto/status/1548845628171722752
voz_ 4y ago
There's soooo many things like this on HN - why is it better than drawing the picture in something like google docs or lucid chart?
- thangalin 4y ago
  My desktop text editor, KeenWrite[0], allows referencing variables within the main document text and figures. KeenWrite uses Kroki[1] to provide a wealth of diagram formats. In the screenshots[2], a Graphviz-based family tree is shown that uses character names sourced from an external YAML file. Those same variables can be used when writing prose. Change the variable in a single location and the family tree is updated and rendered immediately. You can't do that with Google Docs, Lucid Chart, Word, OpenOffice, Scrivener, etc. [0]: https://github.com/DaveJarvis/keenwrite https://github.com/DaveJarvis/keenwrite [1]: https://kroki.io/ https://kroki.io/ [2]: https://github.com/DaveJarvis/keenwrite/blob/master/docs/screenshots.md#variables https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
- chii 4y ago
  you keep the picture "source" in the markdown document, rather than embed a url or link (which can disappear, or go out of date).
  - sgoto 4y ago
    That's precisely it. I wrote down a bit more down below. "Why is it better to write diagrams by hand rather than use a tool (e.g. inkscape, google docs) and export as SVG? Because it requires everybody that wants to edit the diagram to (a) use the same tool and (b) have access to the original source file (e.g. the google doc)." https://twitter.com/samuelgoto/status/1548878038833692672 https://twitter.com/samuelgoto/status/1548878038833692672
    - RugnirViking 4y ago
      for what it's worth, svgs are their own source file, and can typically be edited using any vector editor. I work on a project with several people who regularly trade and collaborate svg's made with inkscape and adobe illustrator without issue. It's possible you meant export as a png or some other non-vector format?
- Veuxdo 4y ago
  I don't think ASCII diagrams are a very good idea, but drag-and-drop tools bring their own problems for engineers. I wrote on this earlier this year: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-and-drop-diagram-tools/ https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...
- spoonjim 4y ago
  It has a built in editable fallback. If you link a LucidChart it can disappear. If you screenshot it, it’s uneditable. If you have a markup based solution, it shows best if everything is working, but if the renderer is broken you still have a working editable ASCII diagram.
systemvoltage 4y ago
The problem with ascii diagrams is that it is difficult to edit. Say you want to move that resistor in the circuit shown in the article. You could use something like Monodraw to combat that, but then I just end up using good ol' power point. There are only handful of instances when ascii diagrams are useful, may be like an IETF proposal.
- sgoto 4y ago
  Yeah, agreed that they are hard to edit if you working by yourself, but disagreed if you are working collaboratively. On "may be like an IETF proposal."", that's precisely where I've been using them the most :) https://fedidcg.github.io/FedCM https://fedidcg.github.io/FedCM Not for everybody, I agree, but it is kinda of ironic that you mentioned "may be like an IETF proposal." :) Also, technical blog posts, e.g. https://code.sgo.to/2022/04/11/metamath.html https://code.sgo.to/2022/04/11/metamath.html https://code.sgo.to/2022/04/28/siop.html https://code.sgo.to/2022/04/28/siop.html
- transfire 4y ago
  Ideally you need a block based editor. Kate is the only modern editor that I’ve used that I know has a block mode. Any others? Now the question is how do you get a block based editor on a webpage?
  - sgoto 4y ago
    I don't think I expect people to edit the diagrams on webpages, rather than locally using their favorite text editor.
    - everybodyknows 4y ago
      Emacs and Vim have rectangle-editing commands, these are essential for reasonably convenient editing. They're so useful, everyone should know them anyway: Need a column of '//' rather than '/* <long_comment_block> */', or vice-versa?. One click-drag and 4-5 keystrokes will do it.
  - drran 4y ago
encryptluks2 4y ago
I find ASCII diagrams to be the opposite of Markdown. Markdown isn't perfect and so that is where extensions come into play, but ASCII diagrams are more like man pages. I think ideally a diagram markup software would use YAML or some other similar convention to show hierarchy while still be readable. Typing and editing ASCII diagrams by hand is simply not convenient.
- sgoto 4y ago
  On YAML-like diagrams, I think you are looking for mermaid [1]. I wrote down here [2] how typograms compare to mermaid [2] in terms of trade-offs. [1] https://github.com/mermaid-js/mermaid https://github.com/mermaid-js/mermaid [2] https://code.sgo.to/typograms/#related https://code.sgo.to/typograms/#related
  - sverhagen 4y ago
    As much as I like Mermaid or PlantUML (more familiar with the last one), how is it YAML or YAML-like?
- Veuxdo 4y ago
  The only tool that I know of that uses YAML for diagrams is Ilograph: https://www.ilograph.com/ https://www.ilograph.com/ But yeah, ASCII for diagrams seems like the worst of all worlds: manual layouts, slow to create, impossible to maintain.
everybodyknows 4y ago
Not on the list of related work is "GoAT" (Go ASCII Tool): https://github.com/blampe/goat https://github.com/blampe/goat
- sgoto 4y ago
  Ah, fair, will add that to the list. But, IIUC, isn't GoAT just a go port of markdeep (which I acknowledge in the related work section)?
  - everybodyknows 4y ago
    Port of the drawing functionality only from Markdeep, and runs on the command line, only.
jcpst 4y ago
Could have something a little more usable if you pasted into a tool like https://asciiflow.com/ https://asciiflow.com/ and then copied your edits back into source. Or an editor plugin with something like the automatic table formatting you get with emacs org-mode.
nathias 4y ago
very cool
ErikCorry 4y ago
This is pretty nice if you have an editor with block mode (like vim) and you are faster with a keyboard than a mouse (most programmers). It integrates well with text based version control and degrades gracefully in that users who don't have the tools and are just looking at the source can probably still read it, and even edit it. I tried using this for the control flow diagrams in V8's regexp implementation, which are documented with ASCII art in jsregexp.cc Results are here: https://twitter.com/erikcorry/status/1548954799290421249 https://twitter.com/erikcorry/status/1548954799290421249 This link explains it better than the page HN links to: https://code.sgo.to/2022/06/20/typographic-diagrams.html https://code.sgo.to/2022/06/20/typographic-diagrams.html It would be an improvement for the page that HN links to if the HTML snippet was surrounded by <body></body> so it worked out of the box. Tips: Don't use underscores for horisontal lines - use dashes (minus signs). A vertical arrow that points at a text will collide with the text unless you add a blank line. Rounded corners are nice. You get these by using . (period) or ' (single quote) instead of + (plus) to join lines. Use period to join to a vertical line below the horizontal line, and single quote to join to a vertical line above the horizontal line.
ofou 4y ago
AWESOME
ThinkBeat 4y ago
I wish each example would also show the source. The site renders a bit strange on my browser right now so perhaps I have just missed it.
- frankenst1 4y ago
  Selecting the text will show the source.
AstroJetson 4y ago
I couldn't get the demo to work without wrapping head and body tags around the appropriate sections. But once I got past that hurdle, it was easy to get some pretty nice pictures drawn. Thanks for the program!
- sgoto 4y ago
  Ha, interesting! Any chance you have a link handy with the problem? Can you expand on what you mean by "head and body tags around the appropriate sections"?
tait 4y ago
In the section on Line Ends, https://code.sgo.to/typograms/ https://code.sgo.to/typograms/ shows a box surrounded by arrows and a dot surrounded by arrows. The arrows that point down (down and left, down, and down and right) are rendering the arrow heads as ascii V's. That seems different than elsewhere on the page. \ | / \ vvv / \ | / v+-----+v vvv ->| |<- ->*<- ^+-----+^ ^^^ / ^^^ \ / | \ / | \
- tait 4y ago
  Hi! This is interesting and I plan to use it for work. Today. In answer to my above inquiry: It looks to me like this section causes consecutive 'v's to be interpreted as text; it might be nice to carve out v's or give alternative glyphs for down arrows or something: if (char.match(/[A-Za-z0-9]/)) { const [, right, , left] = neighbors; str = str || (left.match(/[A-Za-z0-9]/) || right.match(/[A-Za-z0-9]/)); } Also, if you have two arrows coming together diagonally, like: \ / v The arrowhead points to the left rather than straight down. I think straight down would be preferred and not particularly difficult to code. I would be happy to take further conversation/contributions to whatever forum you prefer - what is the best approach?
  - sgoto 4y ago
    That looks like a bug, thanks for finding it! You are welcome to send PRs if you have the inclination! https://github.com/samuelgoto/typograms https://github.com/samuelgoto/typograms
    - sgoto 4y ago
      Ok, submitted a quick fix here: https://github.com/samuelgoto/typograms/commit/40829f6db1a21ea94310d77328e03d2bfe62c742 https://github.com/samuelgoto/typograms/commit/40829f6db1a21...

140 points by sgoto 4y ago

I like this, but - in what contexts will typograms be accepted and rendered? For example, email clients (e.g. Thunderbird) have not even bothered to let us use markdown for email. flowed-format text is about the most you can get out of them for now.

howto1312 4y ago

wentin 4y ago

This is very slick! Regard to editability of text diagram, brainstorming here: it would be cool to have two-way convertibility between text diagram and svg diagram. so users can use drag and drop like interaction to edit the svg diagram, and convert back to text diagram, so it has the best of both worlds. I guess roughly this idea already exists — there is program that converts image to ascii, but it lacks precision, as in the ascii to svg and then back to ascii would yield to different set from the starting point.

sgoto 4y ago

FWIW, I explained a bit why/how I've been using it here: https://twitter.com/samuelgoto/status/1548845628171722752 https://twitter.com/samuelgoto/status/1548845628171722752

voz_ 4y ago

There's soooo many things like this on HN - why is it better than drawing the picture in something like google docs or lucid chart?

thangalin 4y ago
My desktop text editor, KeenWrite[0], allows referencing variables within the main document text and figures. KeenWrite uses Kroki[1] to provide a wealth of diagram formats. In the screenshots[2], a Graphviz-based family tree is shown that uses character names sourced from an external YAML file. Those same variables can be used when writing prose. Change the variable in a single location and the family tree is updated and rendered immediately. You can't do that with Google Docs, Lucid Chart, Word, OpenOffice, Scrivener, etc. [0]: https://github.com/DaveJarvis/keenwrite https://github.com/DaveJarvis/keenwrite [1]: https://kroki.io/ https://kroki.io/ [2]: https://github.com/DaveJarvis/keenwrite/blob/master/docs/screenshots.md#variables https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
chii 4y ago
you keep the picture "source" in the markdown document, rather than embed a url or link (which can disappear, or go out of date).
- sgoto 4y ago
  That's precisely it. I wrote down a bit more down below. "Why is it better to write diagrams by hand rather than use a tool (e.g. inkscape, google docs) and export as SVG? Because it requires everybody that wants to edit the diagram to (a) use the same tool and (b) have access to the original source file (e.g. the google doc)." https://twitter.com/samuelgoto/status/1548878038833692672 https://twitter.com/samuelgoto/status/1548878038833692672
  - RugnirViking 4y ago
    for what it's worth, svgs are their own source file, and can typically be edited using any vector editor. I work on a project with several people who regularly trade and collaborate svg's made with inkscape and adobe illustrator without issue. It's possible you meant export as a png or some other non-vector format?
Veuxdo 4y ago
I don't think ASCII diagrams are a very good idea, but drag-and-drop tools bring their own problems for engineers. I wrote on this earlier this year: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-and-drop-diagram-tools/ https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...
spoonjim 4y ago
It has a built in editable fallback. If you link a LucidChart it can disappear. If you screenshot it, it’s uneditable. If you have a markup based solution, it shows best if everything is working, but if the renderer is broken you still have a working editable ASCII diagram.

systemvoltage 4y ago

The problem with ascii diagrams is that it is difficult to edit. Say you want to move that resistor in the circuit shown in the article. You could use something like Monodraw to combat that, but then I just end up using good ol' power point. There are only handful of instances when ascii diagrams are useful, may be like an IETF proposal.

sgoto 4y ago
Yeah, agreed that they are hard to edit if you working by yourself, but disagreed if you are working collaboratively. On "may be like an IETF proposal."", that's precisely where I've been using them the most :) https://fedidcg.github.io/FedCM https://fedidcg.github.io/FedCM Not for everybody, I agree, but it is kinda of ironic that you mentioned "may be like an IETF proposal." :) Also, technical blog posts, e.g. https://code.sgo.to/2022/04/11/metamath.html https://code.sgo.to/2022/04/11/metamath.html https://code.sgo.to/2022/04/28/siop.html https://code.sgo.to/2022/04/28/siop.html
transfire 4y ago
Ideally you need a block based editor. Kate is the only modern editor that I’ve used that I know has a block mode. Any others? Now the question is how do you get a block based editor on a webpage?
- sgoto 4y ago
  I don't think I expect people to edit the diagrams on webpages, rather than locally using their favorite text editor.
  - everybodyknows 4y ago
    Emacs and Vim have rectangle-editing commands, these are essential for reasonably convenient editing. They're so useful, everyone should know them anyway: Need a column of '//' rather than '/* <long_comment_block> */', or vice-versa?. One click-drag and 4-5 keystrokes will do it.
- drran 4y ago

encryptluks2 4y ago

I find ASCII diagrams to be the opposite of Markdown. Markdown isn't perfect and so that is where extensions come into play, but ASCII diagrams are more like man pages. I think ideally a diagram markup software would use YAML or some other similar convention to show hierarchy while still be readable. Typing and editing ASCII diagrams by hand is simply not convenient.

sgoto 4y ago
On YAML-like diagrams, I think you are looking for mermaid [1]. I wrote down here [2] how typograms compare to mermaid [2] in terms of trade-offs. [1] https://github.com/mermaid-js/mermaid https://github.com/mermaid-js/mermaid [2] https://code.sgo.to/typograms/#related https://code.sgo.to/typograms/#related
- sverhagen 4y ago
  As much as I like Mermaid or PlantUML (more familiar with the last one), how is it YAML or YAML-like?
Veuxdo 4y ago
The only tool that I know of that uses YAML for diagrams is Ilograph: https://www.ilograph.com/ https://www.ilograph.com/ But yeah, ASCII for diagrams seems like the worst of all worlds: manual layouts, slow to create, impossible to maintain.

everybodyknows 4y ago

Not on the list of related work is "GoAT" (Go ASCII Tool): https://github.com/blampe/goat https://github.com/blampe/goat

sgoto 4y ago
Ah, fair, will add that to the list. But, IIUC, isn't GoAT just a go port of markdeep (which I acknowledge in the related work section)?
- everybodyknows 4y ago
  Port of the drawing functionality only from Markdeep, and runs on the command line, only.

jcpst 4y ago

Could have something a little more usable if you pasted into a tool like https://asciiflow.com/ https://asciiflow.com/ and then copied your edits back into source. Or an editor plugin with something like the automatic table formatting you get with emacs org-mode.

nathias 4y ago

very cool

ErikCorry 4y ago

This is pretty nice if you have an editor with block mode (like vim) and you are faster with a keyboard than a mouse (most programmers). It integrates well with text based version control and degrades gracefully in that users who don't have the tools and are just looking at the source can probably still read it, and even edit it. I tried using this for the control flow diagrams in V8's regexp implementation, which are documented with ASCII art in jsregexp.cc Results are here: https://twitter.com/erikcorry/status/1548954799290421249 https://twitter.com/erikcorry/status/1548954799290421249 This link explains it better than the page HN links to: https://code.sgo.to/2022/06/20/typographic-diagrams.html https://code.sgo.to/2022/06/20/typographic-diagrams.html It would be an improvement for the page that HN links to if the HTML snippet was surrounded by <body></body> so it worked out of the box. Tips: Don't use underscores for horisontal lines - use dashes (minus signs). A vertical arrow that points at a text will collide with the text unless you add a blank line. Rounded corners are nice. You get these by using . (period) or ' (single quote) instead of + (plus) to join lines. Use period to join to a vertical line below the horizontal line, and single quote to join to a vertical line above the horizontal line.

ofou 4y ago

AWESOME

ThinkBeat 4y ago

I wish each example would also show the source. The site renders a bit strange on my browser right now so perhaps I have just missed it.

frankenst1 4y ago
Selecting the text will show the source.

AstroJetson 4y ago

I couldn't get the demo to work without wrapping head and body tags around the appropriate sections. But once I got past that hurdle, it was easy to get some pretty nice pictures drawn. Thanks for the program!

sgoto 4y ago
Ha, interesting! Any chance you have a link handy with the problem? Can you expand on what you mean by "head and body tags around the appropriate sections"?

tait 4y ago

In the section on Line Ends, https://code.sgo.to/typograms/ https://code.sgo.to/typograms/ shows a box surrounded by arrows and a dot surrounded by arrows. The arrows that point down (down and left, down, and down and right) are rendering the arrow heads as ascii V's. That seems different than elsewhere on the page. \ | / \ vvv / \ | / v+-----+v vvv ->| |<- ->*<- ^+-----+^ ^^^ / ^^^ \ / | \ / | \

tait 4y ago
Hi! This is interesting and I plan to use it for work. Today. In answer to my above inquiry: It looks to me like this section causes consecutive 'v's to be interpreted as text; it might be nice to carve out v's or give alternative glyphs for down arrows or something: if (char.match(/[A-Za-z0-9]/)) { const [, right, , left] = neighbors; str = str || (left.match(/[A-Za-z0-9]/) || right.match(/[A-Za-z0-9]/)); } Also, if you have two arrows coming together diagonally, like: \ / v The arrowhead points to the left rather than straight down. I think straight down would be preferred and not particularly difficult to code. I would be happy to take further conversation/contributions to whatever forum you prefer - what is the best approach?
- sgoto 4y ago
  That looks like a bug, thanks for finding it! You are welcome to send PRs if you have the inclination! https://github.com/samuelgoto/typograms https://github.com/samuelgoto/typograms
  - sgoto 4y ago
    Ok, submitted a quick fix here: https://github.com/samuelgoto/typograms/commit/40829f6db1a21ea94310d77328e03d2bfe62c742 https://github.com/samuelgoto/typograms/commit/40829f6db1a21...