I recently had to draw some diagrams for documenting something. After looking at various Markdown-friendly options I landed on svgbob[1]. I believe it's a superior solution to these kinds of graph drawing tools for Markdown for one specific reason: the code is still readable. When I go to look at a Markdown file I don't always open the output. I will commonly open up a README file in Vim or just cat it to the terminal. In this case diagrams like those in this post is next to useless. I'm not going to read through some complex drawing definitions and try to visualise the results. With svgbob (or Typograms[2] or any of the other similar options) you can still read the Markdown text document and see the diagrams which is great!
Of course this comes with a tradeoff, drawing the diagrams can be a bit of a pain. But I believe this can be solved by a good Markdown editor or editor plugin. Alternatively a spec like this could be converted into an svgbob-compatible diagram.
Seems like the use-cases are kind of different from the two.
Pikchr seems to be made specifically for A) ease of editing and B) compile to graphs after being embedded in markdown code fences
svgbob I guess would work fine for B, but seems like a hassle to use it for A, but then I've never done ASCII art manually, maybe that's why it seems cumbersome to me?
If you come across this graph and want to edit it, how would you approach it? Because I'm guessing you're not manually moving characters around? Seems like a big hassle if so, even if I'm a daily user of vim which could help a lot.
,─.
( 0 )
`-'
/ \
/ \
V V
,─. ,─.
( 1 ) ( 4 )
`-' `-' .
/ \ | \ `.
/ \ | \ `.
V V | \ `.
,─. ,─. V V V
( 2 ) ( 3 ) ,─. ,─. ,─.
`─' `─' ( 5 ) ( 6 ) ( 7 )
`─' `─' `─'
Yeah this is the drawback I was talking about. Vim certainly helps a bit, but some kind of editor or plugin which allowed you to more easily move stuff around, draw lines, draw boxes and circles, etc. would be very handy. The current approach is moving characters around by hand, which is quite tedious.
> why not use existing tools like plantuml for common diagrams?
Pikchr was created specifically to support the sqlite family of projects and was initially deployed in the markdown processor of the Fossil SCM (one of sqlite's siblings). That whole family of projects avoids third-party dependencies where at all possible for reasons too detailed to type out one-handed on a mobile device.
> That whole family of projects avoids third-party dependencies where at all possible for reasons too detailed to type out one-handed on a mobile device.
For common diagrams, you probably should. I've used Pikchr, and if you want/need to place a lot of things manually or otherwise have a larger degree of control, then it fills that niche OK, I guess. But for whipping up a flowchart or sequence diagram, I find Mermaid or other tools with higher-level abstractions much quicker and simpler.
The big use case is if you need to use Fossil, which only supports Pikchr for inline diagrams. That's a shame IMO, and I would love Mermaid support.
> The big use case is if you need to use Fossil, which only supports Pikchr for inline diagrams. That's a shame IMO, and I would love Mermaid support.
Sidebar...
(A fossil dev here.) That would require third-party code dependencies, something all projects created by Fossil's project lead (Richard Hipp) avoid except where absolutely necessary.
In fossil, the only required 3rd-party dependency is zlib, with libssl highly recommended but not strictly required. Though fossil is heavily dependent on sqlite, they're both by the same main developer so it's not really a 3rd-party dependency. Same goes for JS code like Mermaid - if it's not written by a fossil project member, it doesn't go into the source tree.
I’ll redo my wish into: I wish Pikchr was more expressive. I’m not attached to Mermaid, but I do like things that make the common tasks simple.
AFAICT the Pikchr language is still pretty close to its PIC roots, which is comparatively low level. An expansion to better handle the sort of diagramming that has become common since PIC’s 80s time would be excellent.
This is especially true in the context of Fossil, where being able to make quick flowcharts or sequence diagrams would be super useful.
Sure, but it depends how strongly you care about the security of the supply chain for a core piece of software for our industry, Vs having a more featureful way to make diagrams.
creating inline diagrams to display in documentation or comments in a VCS used to handle sqlite code isn't that much of a security issue IMO. It's bordering on paranoia :)
FWIW/FYI... as someone who has collaborated extensively in the "Hwaci ecosystem," for lack of a better term (projects stemming from Richard Hipp and his company (Hwaci)), i can elaborate a bit on that...
It's not about security in the conventional computing sense, but more about _supply-chain security_. Any third-party components can become unmaintained or break in incompatible ways at any time. The Hwaci ecosystem has a strong culture of avoiding third-party-dependencies, stemming from/related to Richard's definition of freedom: "freedom is being able to take care of yourself," i.e. not depending on others to take care of you. It's important to Richard, and is therefore a part of his projects' cultures, that those who maintain the project are capable of continuing to do so. It's not always feasible to take over maintenance of upstream third-party code, or port away from it, if it suddenly becomes unmaintained. Similarly, it is not always feasible to adapt one's own code to incompatible changes made in upstream third-party code. Avoiding upstream dependencies, despite the obvious annoyance of having to re-invent the wheel at times, inherently gives a developer more freedom over the direction of their own projects. All projects within the Hwaci ecosystem share the trait that they eschew third-party dependencies unless they are (A) unavoidable, (B) non-trivial or non-sensible to reimplement in some minimal form, and (C) ubiquitous (zlib, libssl, and tcl being the counter-examples which most readily come to mind).
I was on the both sides of the spectrum: from everythig custom-built to everything is a third-party dependency.
I guess you managed to find the balance where it works.
Because on the one side it often falls into "oh, we built a PDF writer, and a phone routing system, and a generalised build system from scratch, and now we have no one who knows how these work, how to upgrade them, or replace them". On the other side is "we've been running this PHP 4 project forever because the cost of upgrading every third-party library used across all the breaking changes is at least a three-year project, so we're better off not touching it" :)
Core software is worlds apart from some client app.
Dependencies get compromised, supply chain attacks are extremely real. If you write a webapp do whatever works for you. If you write software with a blast radius as large as SQLite's then please consider not pulling in some vulnerable third party lib for a nice to have.
I'm personally excited to discover pikchr because I periodically need to produce box&arrow style diagrams and everything else from the author has been solid and easy to hack on.
While not embedded in markdown, I like d2 [1]. I can use it with org-babel to embed and view the diagrams on emacs. After using graphviz for years, the visual output seems more polished to me. With that said, I want to give pikchr a try.
It's similar to static site generators - it's easy enough to create a simple one and hundreds of people have but the real differentiator is having hundreds of high quality working templates and aint nobody got time to maintain those.
The CLI diagramming winner will be the one that can easily do 150 different types of diagram out of the box. It might never happen.
Of course this comes with a tradeoff, drawing the diagrams can be a bit of a pain. But I believe this can be solved by a good Markdown editor or editor plugin. Alternatively a spec like this could be converted into an svgbob-compatible diagram.
[1]https://ivanceras.github.io/svgbob-editor/ [2]https://google.github.io/typograms/