Pikchr: A PIC-like markup language for diagrams in technical documentation | Hacker News Reader

Pikchr: A PIC-like markup language for diagrams in technical documentation

pikchr.org

170 pointsgjadi43 comments

Pikchr was created by the same small group that did SQLite, and it is what creates the SQLite diagrams like the ones on this page:

https://sqlite.org/lang_select.html

> the antepenultimate oval object

I laughed at this thinking it was a perfectly cromulent - but completely made up - way of saying “third last” — but I just looked it up and now I feel stupid since it’s actually in the dictionary. Today I learned!

Actually a really common word in Spanish. There are lots of words in english that sound made up that are just literal translations from other languages that non natives use more commonly. Really interesting!

"Overmorrow", for example. Very rare, and the Polish equivalent is used pretty often.

And fourth from last is preantepenultimate.

It comes up when studying ancient greek, if I remember right it is used to describe which syllable gets the accent (ultimate, penultimate, or antepenultimate).

I also recall a shareware Ultima clone for the Amiga back in late 80's or early 90's called "penultima", but I think it's been lost to the sands of time.

This is amazing, considering that I can't really use Mermaid because of its puppeteer/headless browser requirement, and that the documentation is written in... itself.

I'm going to see if there is a Python wrapper for it already, or try to hack one up over the weekend...

Did you try to use https://kroki.io/ as renderer instead?

Seems like a considerable upgrade from PlanUML (https://plantuml.com/ - which is amazing, but sometimes you just can't seem to be able to align the stuff the way you want too). In fact, it seems that the code is slightly less readable compared to PlantUML, I should try to recreate some tangled messes and see how the alignment options work!

Pikchr is quite low-level and could require a considerable high amount of work to get a result.

It feels that way, yes.

I wonder when the line is drawn (pun intended) between an low-level UML description language and a SVG-like formatting language with english words in it. :/

I currently try to create a some middle ground. Basic idea: use eDSL to output drawio xml and use drawio to render a final diagram.

drawio could back many complex things like arrow routing.

WIP output example: https://docs.tuxcare.com/images/eportal-overview.svg

https://pikchr.org/home/pikchrshow for trying it out

What is PIC, referenced in the title and the site copy? The only PIC I know is the microchip line.

https://en.wikipedia.org/wiki/PIC_(markup_language)

This refers to the pic(1) preprocessor to the troff(1) typesetter. Troff is a historical typesetting software with a long history in the Unix ecosystem. Having personally used some of the modern implementations (e.g. GNU troff or groff, heirloom troff) of troff for personal projects, it has been a pleasant experience.

https://troff.org

https://en.wikipedia.org/wiki/Troff

https://en.wikipedia.org/wiki/PIC_(markup_language)

https://www.man7.org/linux/man-pages/man7/roff.7.html

Thanks. I'm familiar with troff, but somehow never came across pic in that context. I have some reading to do!

One of the first “real” applications of Unix was in the AT&T documentation department. It not only reinforced the practicality of the Unixy “small tools linked by pipes” approach, it also encouraged the “little languages” approach to those tools, which brought us lex and yacc as people built things like eqn and pic to feed into troff.

To discover more, just google “unix little languages”.

This is pretty impressive – it starts small, with a very simple way to create a very simple diagram, but the rabbit hole seems to go pretty deep.

That said, whenever I need to create a diagram like this, I just go back to TikZ...

This fills a gap between md/mermaid (easily editable text with no way to do layout) and svg/excalidraw (uneditable text with easily editable custom layouts). I’m not sure people are actually willing to fiddle with that language though without proper wysiwyg tools, at which point you might as well be using svg.

I'm using the language for my school notes and like it, though sometimes it feels too manual.

SVG makes it a trifle hard to connect boxes automatically, which this seems to do effortlessly.

Mermaid also connects boxes automatically. My point was WYSIWYG tools make working with svg just as effortless. The automatic connections are fine, it’s all the manual fiddling that ends up making the markup almost unreadable.

I can’t get behind stuff like this. It just doesn’t seem easier to use than something like Whimsical or even Visio.

Who is the audience? People who want to draw but are afraid to use a mouse? Or can this be automated? But who really automates their documentation?

Dunno… just seems like a lot of work to avoid drawing a drawing.

The plain text representation can be embedded into documentation and tracked by source control. A change to the diagram is a change to the content, not a separate workflow that requires storing the originals somewhere. Updates don't require any third party software.

This fits well into a CMS or static site generator workflow.

Integrated in fossil as well.

https://fossil-scm.org/home/doc/trunk/www/pikchr.md

> I can’t get behind stuff like this. It just doesn’t seem easier to use than something like Whimsical or even Visio.

Different people have different learning/working styles. Even if it doesn't work for you, it may well work for them.

(Personally, I like the directness of tools like Visio, but they very much work at the surface of a visual diagram. It can be useful to express things textually.)

I am asking out of pure ignorance. What would be a good use case for this sorta framework? Whenever I have had to create documentation in the past, I just use draw.io and it has been working well for me so far.

When you need documentation that has to last a _long_ time and be editable by multiple people. Technical diagrams that can be revised and change tracked an item at a time are priceless in those scenarios, whereas you will never know if draw.io will be around in a few years' time.

> you will never know if draw.io will be around in a few years' time.

https://github.com/jgraph/drawio#readme (Apache 2, at least for now)

What if you want to have version changes to the diagrams tracked by git?

Its creators use it for "railroad" syntax diagrams in the SQLite documentation. For example: https://sqlite.org/lang_select.html

I maintain a Markdown-based website. I considered using diagrams to explain certain things. It would be a pain to keep image files and rebuild and export images every time the diagram changes.

Instead I can put the diagram code directly in the Markdown file and update it as needed. Version control would track those changes legibly.

This is very similar to using inlined LaTeX formulas instead of screenshots of the final mathematical formula.

These are the differences to pic: https://pikchr.org/home/doc/trunk/doc/differences.md

It's mostly backwards compatible, with some useful extensions, and without troff embedding support.

does anyone have an example of how to use the (position,position) syntax? I can't get it to work. I can see in the docs it's not recommended, but i've got a lot of diagrams I've been scripting to render using graphviz using explicit positioning that I'd like to try converting.

EDIT: oh too easy you just need the at keyword

```

box at (1,1) "1,1"

box at (4,4) "4,4"

```

This actually looks really nice. Good documentation from the looks of it too.

Can anyone explain to me the advantages of Pikchr over dotfiles?

There is no advantages if you want to splash node relations and get quick and ugly diagram :)).

Mermaid [1] has been good enough for me for years.

[1] https://mermaid.js.org/intro/

And before this, PlantUML was good enough too. It's always worth it to have alternatives. Pikchr is made by the guys who wrote SQLite, and it doesn't need to install a billion NPM dependencies. I think it's worth a try because of this.

This seems a lot more low level than Mermaid.

On the other hand, it can be generated automatically, so conversion is certainly possible.

Unfortunately, Mermaid is difficult to use as a non-frontend library due to its reliance on the DOM API.

Reply on news.ycombinator.com