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

  • 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!

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

  • 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!

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

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

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

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

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

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