Show HN: Typograms, Markdown-like renderer for ASCII diagrams(code.sgo.to)

code.sgo.to

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

https://code.sgo.to/typograms/

39 comments

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.

jcpst4 anni fa

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.

ThinkBeat4 anni fa

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.

frankenst14 anni fa

Selecting the text will show the source.

tait4 anni fa

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
 ->|     |<-           ->*<-
  ^+-----+^             ^^^
 /   ^^^   \           / | \
    / | \

tait4 anni fa

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?

sgoto4 anni fa

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

sgoto4 anni fa

Ok, submitted a quick fix here:

https://github.com/samuelgoto/typograms/commit/40829f6db1a21...

encryptluks24 anni fa

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.

Veuxdo4 anni fa

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.

sgoto4 anni fa

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

sverhagen4 anni fa

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

systemvoltage4 anni fa

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.

sgoto4 anni fa

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

transfire4 anni fa

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?

navane4 anni fa

notepad++ has block editing

CoastalCoder4 anni fa

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

WithinReason4 anni fa

You can move rectangular blocks around in VSCode

drran4 anni fa

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

sgoto4 anni fa

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

everybodyknows4 anni fa

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.

sgoto4 anni fa

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

AstroJetson4 anni fa

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!

sgoto4 anni fa

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

wentin4 anni fa

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.

everybodyknows4 anni fa

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

https://github.com/blampe/goat

sgoto4 anni fa

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

everybodyknows4 anni fa

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

einpoklum4 anni fa

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.

voz_4 anni fa

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?

thangalin4 anni fa

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

chii4 anni fa

you keep the picture "source" in the markdown document, rather than embed a url or link (which can disappear, or go out of date).

sgoto4 anni fa

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

RugnirViking4 anni fa

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?

Veuxdo4 anni fa

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

spoonjim4 anni fa

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.

ofou4 anni fa

AWESOME

nathias4 anni fa

very cool

howto13124 anni fa