Pikchr – PIC-like markup language for diagrams in technical documentation

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

by leonim • 5 years ago

38 12 5 years ago

Pikchr is awesome! I'll just mention that the Markdown-based note-taking app I'm working on as far as I know is the only app on the planet that can syntax-highlight Pikchr code: https://github.com/notable/notable-insiders/releases/tag/v1....

paulsmith• 5 years ago

If it's not immediately apparent, Pikchr is by SQLite creator D. Richard Hipp, and is how SQLite's syntax diagrams are generated on its website.

It's a great little diagram language that's quite capable, and I think of it like a modern web upgrade to Brian Kernighan's PIC.

otherflavors• 5 years ago

contrary to pikchr documentation, troff is not obsolete

wyoung23• 5 years ago

No technology popular enough to attract an audience ever goes away. However, would you care to speculate on how many troff documents were written in 2021 versus Markdown docs?

OJFord2• 5 years ago

Pikchr is designed to be embedded in fenced code blocks of Markdown

Odd choice, usually that's how you'd show the (possibly syntax-highlighted) code as-is, not execute/render it in situ.

E.g. what if I want a document that says 'this pikchr code generates this'? I'd expect to write something like:

    ```pikchr
    arrow 200% "whatever"
    ```
    renders:
    $pikchr
    arrow 200% "whatever"
    $

(Or some other syntax) not the code block twice, once with some kind of escaping.

kragen• 5 years ago

That's maybe the most interesting idea out of the whole setup!

You could reasonably put options on the fenced-code-block header line:

    ```pikchr --source
    ...
    ```

    ```pikchr --caption  # caption rendered figure with source
    ...
    ```

I don't know if pikchr supports anything like this, but it seems like you could add it pretty easily if you wanted to.

wyoung23• 5 years ago

If you leave off the "pikchr" tag or use something else like "PikchrSource", then the renderer doesn't trigger.

If you want to see it both ways, Fossil renders the diagrams with an Alt or Ctrl-click handler attached (depending on platform) that toggles between the SVG and the fixed-width source code view.

And if you don't like the modifier key, you can tag a diagram "pikchr toggle" to make it toggle with a simple left-click.

OJFord2• 5 years ago

Sure, but usually specifying "pikchr" (or whatever) means syntax-highlight as appropriate to that language; not execute as that language.

electroly• 5 years ago

Pikchr is really great. The syntax looks strange at first, but the learning curve is actually low. Within 5 minutes of looking at the pikchr source of some SQLite diagrams, you'll get it. I use it to produce railroad syntax diagrams in the same style as the ones in the SQLite docs. I don't use the Markdown integration; I just generate SVGs using PikchrShow[0] and treat them as images in my HTML-based docs.

[0] https://pikchr.org/home/pikchrshow

wyoung23• 5 years ago

I'm the type of guy that would store the Pikchrs in the version control system alongside the HTML, then write a Makefile to regenerate the SVGs referenced from the HTML every time the Pikchrs change.

But at that point, you might as well just use Fossil as a CMS. :)

https://fossil-scm.org/home/doc/trunk/www/wikitheory.wiki

danshearer• 5 years ago

I have used both Pikchr and several of the Mediawiki extensions for diagrams (the most recently-maintained of which is https://www.mediawiki.org/wiki/Extension:Flex_Diagrams )

Here is my earliest Pikchr effort: https://lumosql.org/src/not-forking (click to see source.)

Pikchr diagrams are crisp and precise with zero configuration. Mermaid diagrams are difficult to make render as nicely as the screenshots show (https://mermaid-js.github.io ) and easier to confuse with ambiguous syntax.

With the addition of 5 lines Lua, Pandoc now handles Pikchr in Markdown documents: https://groups.google.com/g/pandoc-discuss/c/zZSspnHHsg0/m/m...

srvmshr• 5 years ago

I wasn't aware of this & looks like worth learning. I was looking ahead to learn Penrose (https://penrose.ink/) for making diagrams in my notes.

Pikchr – PIC-like markup language for diagrams in technical documentation

Related Stories