4 ms·

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

38 points by leonim 5y ago

srvmshr 5y ago
I wasn't aware of this & looks like worth learning. I was looking ahead to learn Penrose (https://penrose.ink/ https://penrose.ink/) for making diagrams in my notes.
fabiospampinato 5y 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.9.0-beta.4 https://github.com/notable/notable-insiders/releases/tag/v1....
paulsmith 5y 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 5y ago
contrary to pikchr documentation, troff is not obsolete
- wyoung2 5y 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?
OJFord 5y 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 5y 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.
- wyoung2 5y 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.
  - OJFord 5y ago
    Sure, but usually specifying "pikchr" (or whatever) means syntax-highlight as appropriate to that language; not execute as that language.
electroly 5y 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 https://pikchr.org/home/pikchrshow
- wyoung2 5y 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 https://fossil-scm.org/home/doc/trunk/www/wikitheory.wiki
danshearer 5y 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 https://www.mediawiki.org/wiki/Extension:Flex_Diagrams ) Here is my earliest Pikchr effort: https://lumosql.org/src/not-forking 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 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/mxgoOHm0AQAJ https://groups.google.com/g/pandoc-discuss/c/zZSspnHHsg0/m/m...

38 points by leonim 5y ago

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

fabiospampinato 5y 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.9.0-beta.4 https://github.com/notable/notable-insiders/releases/tag/v1....

paulsmith 5y 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 5y ago

contrary to pikchr documentation, troff is not obsolete

wyoung2 5y 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?

OJFord 5y 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 5y 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.
wyoung2 5y 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.
- OJFord 5y ago
  Sure, but usually specifying "pikchr" (or whatever) means syntax-highlight as appropriate to that language; not execute as that language.

electroly 5y 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 https://pikchr.org/home/pikchrshow

wyoung2 5y 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 https://fossil-scm.org/home/doc/trunk/www/wikitheory.wiki

danshearer 5y 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 https://www.mediawiki.org/wiki/Extension:Flex_Diagrams ) Here is my earliest Pikchr effort: https://lumosql.org/src/not-forking 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 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/mxgoOHm0AQAJ https://groups.google.com/g/pandoc-discuss/c/zZSspnHHsg0/m/m...