Typograms: A definition and renderer for ASCII diagrams | Hacker News Reader

Typograms: A definition and renderer for ASCII diagrams

google.github.io

162 pointssgoto58 comments

> A polyfill is available that allows you use to use it in browsers.

This isn’t a polyfill. Polyfills are about implementing new native stuff on old environments, but no browser is going to be including this any time soon, and certainly not in this form—

> <script type="text/typogram">

This should use <pre> instead, e.g. <pre class="typogram">. It’s content, not scripting, and if the JavaScript isn’t run (for whatever reason—JS is less reliable than people often think, especially third-party JS, even on environments that don’t try to block it) you’d like the diagram to still be visible in some form.

(Retaining the <pre> would also be a great improvement for selecting text—the current arrangement of “place single-character <text> elements” is almost useless for copy and paste (losing spaces and line breaks), which is the main reason I can imagine wanting such a thing. If character sizes and aspect ratios are a concern, control that stuff with scaling transforms or line-height, and detect and contain (e.g. <span style="overflow:visible;width:…">…</span>) individual characters that are falling out of the grid due to font fallback or bad ligatures like Nimbus Mono <https://github.com/ArtifexSoftware/urw-base35-fonts/issues/3...>.)

> if the JavaScript isn’t run [...] you’d like the diagram to still be visible in some form.

Yeah, that's one of the things that disappointed me about the linked page, I expected the diagrams to degrade gracefully into regular ASCII-art.

One of the ways I could imagine using this being useful is in markdown documents, following the principle that the source is good-enough to follow even if some additional processing could make it better.

Fair point on the point on the term polyfill. Done, replaced it with "JS renderer" [1].

[1] https://github.com/google/typograms/commit/4270c0ad387a2b500...

> This should use <pre> instead

I'd say that this is the perfect use case for a custom element

So this is basically just what we used to do in IBM Extended ASCII like thirty-five (forty?) years ago, only slightly expanded because Unicode has more characters than Codepage... Uh, 472? 185? I forget. But anyway, wow: So much time, so little progress.

Typograms could be great with the monodraw app on macOS. I'm a very happy customer of monodraw-- not affiliated in any way.

https://monodraw.helftone.com/

I love Monodraw. I've been searching for a non-Mac equivalent for years and have so far come up empty handed.

What sets Monodraw apart as compared to something like ASCIIFlow?

It works.

At least ASCII flow is very very buggy on my Mac. And I’ve attempted with many web browsers.

That said, I’m hopeful that it improves its usability and it’s pretty awesome that it is open source and can be run locally which reminds me of hastebin.

Monodraw has an understanding of objects in an ascii drawing. For example, you can select a box and edit the properties of it, or easily move just the box and not boxes within it.

Essentially it's a full flowchart editor that just outputs ascii.

I'm working on it. I'm the author of svgbob, but it will take me awhile to polish this. https://ivanceras.github.io/bob-editor/

Thank you for svgbob, I adore it.

Previously submitted in personal repo:

https://news.ycombinator.com/item?id=32133345

Now, officially open sourced:

https://github.com/google/typograms

Thank you, this looks really useful!

One more ASCII-based tool that you could add into your workflow is https://arthursonzogni.com/Diagon/#Sequence which can be used to generate the ASCII that you input into Typogram.

For example, input:

  Renderer -> Browser: BeginNavigation()
  Browser -> Network: URLRequest()
  Browser <- Network: URLResponse()
  Renderer <- Browser: CommitNavigation()
  Renderer -> Browser: DidCommitNavigation()

will output the following sequence diagram:

  .--------.            .-------.     .-------.
  |Renderer|            |Browser|     |Network|
  '--------'            '-------'     '-------'
      |                     |             |    
      |  BeginNavigation()  |             |    
      |-------------------->|             |    
      |                     |             |    
      |                     |URLRequest() |    
      |                     |------------>|    
      |                     |             |    
      |                     |URLResponse()|    
      |                     |<------------|    
      |                     |             |    
      | CommitNavigation()  |             |    
      |<--------------------|             |    
      |                     |             |    
      |DidCommitNavigation()|             |    
      |-------------------->|             |    
  .--------.            .-------.     .-------.
  |Renderer|            |Browser|     |Network|
  '--------'            '-------'     '-------'

and then you can perform further edits using something like https://asciiflow.com/ (web, free) or https://ivanceras.github.io/bob-editor/ (web, free) or https://monodraw.helftone.com/ (Mac only, proprietary) as mentioned in other comments.

But like, why not just use that ASCII sequence diagram directly?

    Renderer               Browser        Network
    ========               =======        =======
    | BeginNavigation      |              |  
    |--------------------->|              |  
    |                      | URLRequest   |
    |                      |------------->|
    |                      |              |
    |                      |  URLResponse |
    |                      |<-------------|
    |                      |
    |     CommitNavigation |
    |<---------------------|
    |                      |
    | DidCommitNavigation  |
    |--------------------->|
    |

This took me like 45 seconds to produce in Visual Studio Code.

I'm somewhat confused: the "Related" section says:

"[...] that motivated me to rewrite it [- presumably: svgbob -] in JS (svgbob is written in rust)" [...]"

So, is "Typograms" a modified rewrite of svgbob in JS? IF yes, isn't it a Derivative Work of svgbob, and (per the Apache License, which seems to match the one used here) shouldn't "Typograms" keep the mention of the original author somewhere in the Licensing information, and notably their original Copyright note? (As present e.g. in svgbob's License file.)

IF NOT, then why mention a "rewrite"? What is actual relation of Typograms to svgbob? This becomes even weirder given that some of the examples in the Typograms demo seem reused verbatim from the svgbob demo - but rendered poorer (at least on Firefox); making it sound like it is a rewrite also makes it sound like it is a - sorry for this - crappy rewrite... and this under google's name... but then in the end is it actually not a rewrite? is it just a - still at first glance seemingly crappy, sorry - clone? (hm, at least I'd love to show some clearly highlighted improvements over svgbob, maybe? if I'm not to focus on the somewhat-broken parts of the demo?) aaaand still under google's name?... reeeeaaaaaallllyyyyy wierd and confusing case to me... (O_o)

A rewrite is NOT a derivative work, as long as it is only copying the interfaces and not original code.

Hmm, IANAL, though I seem to believe there tends to be a question of "have you seen the original code before writing your clone" - which presumes that you still risk copying some code - or are you doing a "cleanroom reimplementation" without ever at all seeing the original code, just basing purely on a specification of the original, ideally written by someone else. As long as it's not pristine cleanroom, I think it's potentially murky territory.

Done, merged a patch to clarify that it is absolutely the latter: this is an implementation from scratch with completely different rendering passes, design and SVG output structures.

Does that help?

https://github.com/google/typograms/commit/bdd329eaec7497b96...

It does, thanks! <3

An implementation by someone not involved in the original, and not using the original code, is not usually called a rewrite. The authors of this should use more careful language.

If the same author wrote one version and then another, and only a minority of the code (if any) is shared between the two, it's a rewrite. Especially if the new thing is intended to replace the old.

If one employee at an organization produced the first version of something, and another one at the same organization produces the second, using very little of the original code, that's also rewrite. The organization is doing a rewrite, even though that second employee is writing it for the first time.

Someone not connected to the original who knows only the interfaces, or inputs and outputs, isn't doing a rewrite; they are "cloning" or "implementing" and such.

As someone who is heavily biased against anything Google, the "related work" paragraph positively surprised me. I wish more software authors would point out alternatives in what I can only describe as a user friendly and generous manner.

Google is made of people and Sam is a delightful person that you don't need to be "biased" against.

Yeah, I know that wonderful individuals work there. As is true for Microsoft and even Facebook and so on. But I saw google.github and was looking for something to not like about it, I have to admit that, and I found nothing. Kudos and thanks to the author.

As someone who's contributed to one of the "related" alternatives, I'm struck by the beauty of a JS-based solution. With the browser able to produce the SVGs on its own, on demand, they need never be stored (assuming all viewing is to be done in a browser).

Examples of actual typograms [0]: https://aaronkuehn.com/art

[0] https://en.wiktionary.org/wiki/typogram

So how do I easily draw? I can see potential to use it in documentation and etc but how do I create e.g. mock? Just typing all the symbols I need to remember?

Or have an LLM do it after indexing the project.

I've asked ChatGPT to render simple alphabet letters in ASCII art and it gives ridiculous results. It seems like the worst skill it has.

Many diagrams I am able to draw manually as I'm editing source code on emacs, but for more complicated ones I tend to use this: https://asciiflow.com . To each their own, so pick your favorite ASCII editor.

Selecting text in the example diagrams somehow reminds me of Carpenter's "They Live", where the protagonist has glasses to see through the superficial appearance of people and billboards.

That said, I haven't seen this or the mentioned related work before, and it's really neat how easy it is to create good looking and very readable diagrams with this.

This would combine really nicely with virtualedit=true in vim

Oooohhh neat! By the way, virtualedit takes a string, can be block, onemore, all, or none.

ASCII diagrams can easily be drawn and maintained directly. That's kind of the whole point! Generating them from some more primitive declaration language makes them harder to use, not easier. This kind of tool is frustrating.

No; these diagrams are not drawn from a semantic declaration language. They are drawn from ASCII diagrams. They are just inferring a "skin" made of nicer-looking Unicode symbols.

The examples don't show the source code next to them, but you can just view the page source in your browser (e.g. Ctrl-U in Firefox).

So the purpose of the tool is to transform an ASCII diagram to a Unicode diagram? I struggle to understand the value of such a thing.

    +---+   +---+
    | A |-->| B |
    +---+   +---+

is actually better than

    ┌─┐ ┌─┐
    │A│→│B│
    └─┘ └─┘

because it can be manipulated without external tools. Right?

Maintaining them by hand seems like a really excessive level of manual work. Most tools are basically raster drawing based, and raster graphics requires you to have a general layout of where things go in your head, or else spend a lot more time on the trial and error.

This has never been my experience. Any editor with multi-cursor support can easily be used to produce or maintain ASCII diagrams like the ones described so far.

I've never used multi-cursor, but it still seems harder than markup, or vector graphics. If you do anything complex, and you're not happy with your layout, you can't just drag the boxes around.

Seems like you'd kind of have to have a clear idea of where everything goes before you start to really work effectively. Or is that part of the appeal, practicing skills you normally would use as a coder?

The nice thing about ASCII diagrams is that they they naturally push back against complexity. That is, a diagram that's too complex to express in ASCII is (almost always) too complex in general. And the nice thing about doing ASCII diagrams manually in a (multi-cursor capable) editor is that this essential property is reinforced at the editing stage.

Definitely you should have a clear idea of your diagram before you arrive at your editor. If you want to experiment with layouts or whatever, you do that in a different tool, often pen-and-paper.

As you note, the same is true of programming! Experimentation is a totally different modality than writing a production-quality program. It's not a spectrum, you're either doing one or the other.

edit But, really, if you have a reasonable diagram in your head, it's really not difficult at all to express it as ASCII in a (multi-cursor capable) editor. I can do diagrams faster in VS Code than Monodraw, usually.

That's interesting that there's an actual reason!

I always thought they were kind of like the art you see on silicon chips, not really practical but accepted because trying to only do 100% practical things for a solid 8 hours isn't really the best plan, and only done by the programmers with a talent for raster art in general.

It does seem a bit time consuming unless you have a strong ability to visualize entire layouts. Being able to imagine 3 boxes is a lot different from being able to imagine 3 boxes on a screen all at once in proportion, and that's pretty far outside of what programmers ever are trained for unless you specifically seek out ways to learn that.

Using real pen and paper for diagrams is an interesting idea! Sometimes I see other coders with a notepad on their desk but I never got into it and am never quite sure what it's for, usually people seem to be making a lot of bullet points of text.

Yeah, diagramming with ASCII in a text editor is actually quite virtuous!

I wonder if it would be useful to publish a series of screen-capture videos demonstrating how to build these kind of diagrams. It's really not difficult!

Text clips on the top side on firefox android, which is quite embarrassing

Same in desktop version of Firefox.

Also, the examples in the last 3 sections in "Scribbles" ("Small curved steps", "Parenthesis and spheres", "Diagonal Side-way Arrows") don't seem to actually render anything interesting, just showing what is presumably the original ASCII-Art behind them. I'm confused if that's what was intended there, or something is broken (?)

edit: The whole situation is even weirder given that half of the motivation claimed by the author in the "Related" section is apparently specifically: "ran into enough challenges with [...] the text rendering [in svgbob ...] that motivated me to rewrite it in JS (svgbob is written in rust)". I mentioned my confusion about relation to svgbob in a top-level comment here, but the quote above makes it even weirder to have Typograms actually render text poorly (in Firefox)... and the jokes and tropes just seem to want to write themselves here, whether about rewriting Rust in JS, or about Google ignoring Firefox...

Cute.

But if the maintainer(?) is reading these comments it looks like the inductor in the circuit section isn't working correctly. I can separate "C" characters rather than the normal circuit symbol

Maintainer(!) here, reading the comments! Can you help me understand what you'd expect? I can't really find the "inductor" you are referring to and the "C" character that seems off to you. Care to expand a bit so that I can try to fix?

Hiya,

In the "Circuit" section there is the text "30uH" and a few characters to the right of that there is a column with 3 "C" characters arranged vertically. Next to each "C" character is a pipe "|" character.

The standard unit of inductance is the henry (H) so I assume 40uH is the value of that component and therefore I would expect that arrangement of 6 characters to map to an inductor symbol: ( https://commons.wikimedia.org/wiki/File:Inductor_Symbols.jpg ) rather than staying as separate C characters with a vertical line next to it.

(If this is a bug with my browser then I can only say that I'm using Chrome on MacOS and everything else looks correct)

There is a lot of alternatives before of google, for example Ditaa https://github.com/stathissideris/ditaa .

There is a small list (in spanish) in: https://tomatesasesinos.com/2020/06/11/anti-nocodetools-diag...

shameless self plug of my very small collection of ascii data viz libraries

https://ascii.dataviz.gallery/

planning to grow it soon with a more thorough breakdown of what libraries are available for what programming languages

Looking forward to seeing more.

Neat! Want to send a PR with some of these diagrams as examples?

> Typograms optimizes for editability and portability (e.g. plain text is easy to maintain, change, store and transmit), at the cost of expressivity (e.g. SVG is more expressive) and ergonomics (e.g. higher level tools produce diagrams faster).

How can it be both “easy to change” and not be ergonomic?

Because the editing is at the character level.

If you look at the page source, this is what the grids look like for instance:

    +----+        +----+                                                                                                         
   /      \      /      \            .-----+-----+-----.                                                                         
  +        +----+        +----+      |     |     |     |          .-----+-----+-----+-----+                                      
   \      /      \      /      \     |     |     |     |         /     /     /     /     /                                       
    +----+        +----+        +    +-----+-----+-----+        +-----+-----+-----+-----+                                        
   /      \      /      \      /     |     |     |     |       /     /     /     /     /
  +        +----+        +----+      |     |     |     |      +-----+-----+-----+-----+
   \      /      \      /      \     +-----+-----+-----+     /     /     /     /     /
    +----+        +----+        +    |     |     |     |    +-----+-----+-----+-----+
          \      /      \      /     |     |     |     |   /     /     /     /     /
           +----+        +----+      '-----+-----+-----'  '-----+-----+-----+-----+

That's easy to change, but even for the top Vim slingers, it's not that ergonomic to produce by text editing.

You could benefit from tooling to produce the underlying ASCII diagrams; this tool is just a renderer to make them look nicer.

Exactly.

This reminds me I still have to learn Pikchr, the diagramming language used to render SQLite syntax diagrams.

https://pikchr.org/home/doc/trunk/homepage.md

Its amazing, we can have thousands of emoticons, but not the more complex ascii to use for boxes.

The old extended-ASCII line drawing characters are still there in Unicode.

how would you export something like this to an image? and also, would this work in github markdown?

Reply on news.ycombinator.com