Show HN: Typograms, Markdown-like renderer for ASCII diagrams (opens in new tab)

(code.sgo.to)

140 pointssgoto3y ago38 comments

38 comments

35 comments · 14 top-level

systemvoltage3y ago· 7 in thread

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.

sgotoOP3y 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

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/28/siop.html

transfire3y 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?

sgotoOP3y ago

I don't think I expect people to edit the diagrams on webpages, rather than locally using their favorite text editor.

1 more reply

navane3y ago

notepad++ has block editing

CoastalCoder3y ago

> Kate is the only modern editor that I’ve used that I know has a block mode. Any others?

Depending on how you define "modern", vim (and I assume neo-vim) support block-mode.

WithinReason3y ago

You can move rectangular blocks around in VSCode

drran3y ago

mcedit in mc file manager has block mode selection (Shift-F3).

voz_3y ago· 5 in thread

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?

Veuxdo3y 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-an...

thangalin3y 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

[1]: https://kroki.io/

[2]: https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...

chii3y 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).

sgotoOP3y 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

1 more reply

spoonjim3y 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.

encryptluks23y ago· 3 in thread

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.

Veuxdo3y ago

The only tool that I know of that uses YAML for diagrams is Ilograph: https://www.ilograph.com/

But yeah, ASCII for diagrams seems like the worst of all worlds: manual layouts, slow to create, impossible to maintain.

sgotoOP3y 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 [2] https://code.sgo.to/typograms/#related

sverhagen3y ago

As much as I like Mermaid or PlantUML (more familiar with the last one), how is it YAML or YAML-like?

tait3y ago· 2 in thread

In the section on Line Ends, 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
 ->|     |<-           ->*<-
  ^+-----+^             ^^^
 /   ^^^   \           / | \
    / | \

tait3y 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?

sgotoOP3y 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

1 more reply

everybodyknows3y ago· 2 in thread

Not on the list of related work is "GoAT" (Go ASCII Tool):

https://github.com/blampe/goat

sgotoOP3y 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)?

everybodyknows3y ago

Port of the drawing functionality only from Markdeep, and runs on the command line, only.

ThinkBeat3y ago· 1 in thread

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.

frankenst13y ago

Selecting the text will show the source.

AstroJetson3y ago· 1 in thread

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!

sgotoOP3y 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"?

ErikCorry3y 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

This link explains it better than the page HN links to: 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.

jcpst3y ago

Could have something a little more usable if you pasted into a tool like 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.

sgotoOP3y ago

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

wentin3y 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.

einpoklum3y 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.

ofou3y ago

AWESOME

nathias3y ago

very cool

j / k navigate · click thread line to collapse

38 comments

35 comments · 14 top-level

systemvoltage3y ago· 7 in thread

sgotoOP3y 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

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/28/siop.html

transfire3y 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?

sgotoOP3y ago

I don't think I expect people to edit the diagrams on webpages, rather than locally using their favorite text editor.

1 more reply

navane3y ago

notepad++ has block editing

CoastalCoder3y ago

> Kate is the only modern editor that I’ve used that I know has a block mode. Any others?

Depending on how you define "modern", vim (and I assume neo-vim) support block-mode.

WithinReason3y ago

You can move rectangular blocks around in VSCode

drran3y ago

mcedit in mc file manager has block mode selection (Shift-F3).

voz_3y ago· 5 in thread

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?

Veuxdo3y ago

thangalin3y ago

You can't do that with Google Docs, Lucid Chart, Word, OpenOffice, Scrivener, etc.

[0]: https://github.com/DaveJarvis/keenwrite

[1]: https://kroki.io/

[2]: https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...

chii3y 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).

sgotoOP3y 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

1 more reply

spoonjim3y ago

encryptluks23y ago· 3 in thread

Veuxdo3y ago

The only tool that I know of that uses YAML for diagrams is Ilograph: https://www.ilograph.com/

But yeah, ASCII for diagrams seems like the worst of all worlds: manual layouts, slow to create, impossible to maintain.

sgotoOP3y 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 [2] https://code.sgo.to/typograms/#related

sverhagen3y ago

As much as I like Mermaid or PlantUML (more familiar with the last one), how is it YAML or YAML-like?

tait3y ago· 2 in thread

In the section on Line Ends, 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
 ->|     |<-           ->*<-
  ^+-----+^             ^^^
 /   ^^^   \           / | \
    / | \

tait3y 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?

sgotoOP3y 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

1 more reply

everybodyknows3y ago· 2 in thread

Not on the list of related work is "GoAT" (Go ASCII Tool):

https://github.com/blampe/goat

sgotoOP3y 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)?

everybodyknows3y ago

Port of the drawing functionality only from Markdeep, and runs on the command line, only.

ThinkBeat3y ago· 1 in thread

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.

frankenst13y ago

Selecting the text will show the source.

AstroJetson3y ago· 1 in thread

sgotoOP3y 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"?

ErikCorry3y ago

This link explains it better than the page HN links to: 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.

jcpst3y ago

Could have something a little more usable if you pasted into a tool like 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.

sgotoOP3y ago

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

wentin3y ago

einpoklum3y 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.

ofou3y ago

AWESOME

nathias3y ago

very cool

j / k navigate · click thread line to collapse