5 ms·

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

77 points by smartmic 6y ago

gnabgib 6y ago
This was posted [9 days ago](https://news.ycombinator.com/item?id=24514001 https://news.ycombinator.com/item?id=24514001)
zeckalpha 6y ago
Seems comparable to https://graphviz.org/ https://graphviz.org/ Perhaps pikchr is more flexible but more verbose?
- vinodkd 6y ago
  No, this is different. Graphviz is primarily about laying graphs out, and secondarily (if that) about using them to draw diagrams. This is an "open canvas" diagram description language and tool. The closest I can think of is ditaa (ditaa.sourceforge.net), but ditaa's front end is completely different - it requires you to actually "draw" the picture using text. pikchr (and PIC before it) requires you to describe the picture using words and it will draw it for you. Plantuml and Websequencediagrams have frontends that are similar, but they are constrained in domain-specific ways. This is any 2D picture (well, within the primitives supported) Plantuml, IIRC, uses Graphviz in the backend and is in impressive attempt at hiding that fact :). I have spent many a hour trying to get Graphviz to lay a diagram out they way I want it to before learning that the one true way is to let Graphviz be itself - a displayer of the network you described to it, not a displayer of the diagram you want to see.
  - chii 6y ago
    Pikchr has more in common with svg i think.
genericlogic 6y ago
I love the concept of using text to create visuals. It greatly appeals to my sensibilities as a coder. The concept of being able to source control the data seems amazing in theory. What I found though was that once a diagram hits sufficient complexity the effort to produce a visual appealing image became too great. I likely could spend more time learning tools like graphviz and mermaid - but I find my time better spent in in more traditional graphic tools (lucid charts, Visio etc). I don't proclaim this to be the great truth on these tools, merely my experience.
- sgbeal 6y ago
  FWIW, pikchr is not intended to be used to create "marketing materials," but solely for dry/boring technical diagrams (not that that's a bad thing - i'm all for dry/boring diagrams). It certainly excels at simple diagrams but likely won't fit the needs of those creating presentations for their CEOs, CFOs, or most other C's-of-O's. Since it exports to SVG, and the Fossil SCM's new "pikchrshow"[^1] feature allows users to easily preview pikchrs and copy the generated SVG to the clipboard, pikchr becomes a potentially interesting option for generating parts of larger diagrams and importing those parts into one's SVG-capable editor of choice. i've started collecting "pikmoji" from contributors over at https://fossil.wanderinghorse.net/r/pikmojicon https://fossil.wanderinghorse.net/r/pikmojicon, for use in copy/pasting into one's own pikchrs. [^1] = https://pikchr.org/home/pikchrshow https://pikchr.org/home/pikchrshow (full disclosure: i added that feature fossil)
  - tveyben 6y ago
    >i've started collecting "pikmoji" from... Hmm - as ‘pik’ means ‘dick’ in danish, i have a hard time imaging with ‘pikmoji’s trying to imagine what they would look like in this time of #MeeToo... Not so long ago there was a thread about avoiding ‘bad’ names in foreign languages, this name clearly Spawn interesting associations in Denmark :-)
- vinodkd 6y ago
  I agree, and you can see this even with "simple" diagrams. For example, the Pikchr examples page[1] has a SQLite architecture diagram, and if you click through to the source (like the idea of "click to see source" btw), you'll find lines like this: line invis from 0.25*$margin east of last.sw up last.ht \ "Backend" italic aligned ...which is an invible line used to create a label for the box that's vertically aligned. This is the kind of "toil" that adds up to what you describe. Ideally, this should be a feature of the language itself, something like box "label" valigned nw but you cannot anticipate every bit of adjustment users would need to produce a visually appealing image, since that's subjective. PIC has macros[2] that somewhat make this easier, but as things get larger you'd still have the issues you mention, and you're trading one complexity (hand drawing visually appealing picture) for another (maintaining more complicated code for local visual appeal). I dont know if pikchr supports macros (which are more like functions since troff is a full fledged language, and less like svg symbols afaict) 1: https://pikchr.org/home/doc/trunk/doc/examples.md https://pikchr.org/home/doc/trunk/doc/examples.md 2: http://floppsie.comp.glam.ac.uk/Glamorgan/gaius/web/pic-14.html#14.%20Macros http://floppsie.comp.glam.ac.uk/Glamorgan/gaius/web/pic-14.h...
nattaylor 6y ago
>Any existing Markdown or other wiki rendering engine that can invoke a C-language library should be able to integrate Pikchr quickly and easily. Sounds lightweight! I wonder if that will help with adoption
- vinodkd 6y ago
  Well, the author's other "single C file dependency" project is somewhat popular I hear, so maybe.
- sgbeal 6y ago
  > Sounds lightweight! Its public API is literally a single function. You give it pikchr code and it returns a string which contains either an SVG or a description of an error it ran across. (You, the user, can determine which it is by the state of an output parameter (integer pointer).)
  - nattaylor 6y ago
    So Pandoc written in Haskell ought to be easy to integrate, right?
hardwaresofton 6y ago
The example listing looks fantastic: https://pikchr.org/home/doc/trunk/doc/examples.md https://pikchr.org/home/doc/trunk/doc/examples.md
octetta 6y ago
Anyone here working on vscode integration for pikchr?

77 points by smartmic 6y ago

This was posted [9 days ago](https://news.ycombinator.com/item?id=24514001 https://news.ycombinator.com/item?id=24514001)

zeckalpha 6y ago

Seems comparable to https://graphviz.org/ https://graphviz.org/ Perhaps pikchr is more flexible but more verbose?

vinodkd 6y ago
No, this is different. Graphviz is primarily about laying graphs out, and secondarily (if that) about using them to draw diagrams. This is an "open canvas" diagram description language and tool. The closest I can think of is ditaa (ditaa.sourceforge.net), but ditaa's front end is completely different - it requires you to actually "draw" the picture using text. pikchr (and PIC before it) requires you to describe the picture using words and it will draw it for you. Plantuml and Websequencediagrams have frontends that are similar, but they are constrained in domain-specific ways. This is any 2D picture (well, within the primitives supported) Plantuml, IIRC, uses Graphviz in the backend and is in impressive attempt at hiding that fact :). I have spent many a hour trying to get Graphviz to lay a diagram out they way I want it to before learning that the one true way is to let Graphviz be itself - a displayer of the network you described to it, not a displayer of the diagram you want to see.
- chii 6y ago
  Pikchr has more in common with svg i think.

genericlogic 6y ago

I love the concept of using text to create visuals. It greatly appeals to my sensibilities as a coder. The concept of being able to source control the data seems amazing in theory. What I found though was that once a diagram hits sufficient complexity the effort to produce a visual appealing image became too great. I likely could spend more time learning tools like graphviz and mermaid - but I find my time better spent in in more traditional graphic tools (lucid charts, Visio etc). I don't proclaim this to be the great truth on these tools, merely my experience.

sgbeal 6y ago
FWIW, pikchr is not intended to be used to create "marketing materials," but solely for dry/boring technical diagrams (not that that's a bad thing - i'm all for dry/boring diagrams). It certainly excels at simple diagrams but likely won't fit the needs of those creating presentations for their CEOs, CFOs, or most other C's-of-O's. Since it exports to SVG, and the Fossil SCM's new "pikchrshow"[^1] feature allows users to easily preview pikchrs and copy the generated SVG to the clipboard, pikchr becomes a potentially interesting option for generating parts of larger diagrams and importing those parts into one's SVG-capable editor of choice. i've started collecting "pikmoji" from contributors over at https://fossil.wanderinghorse.net/r/pikmojicon https://fossil.wanderinghorse.net/r/pikmojicon, for use in copy/pasting into one's own pikchrs. [^1] = https://pikchr.org/home/pikchrshow https://pikchr.org/home/pikchrshow (full disclosure: i added that feature fossil)
- tveyben 6y ago
  >i've started collecting "pikmoji" from... Hmm - as ‘pik’ means ‘dick’ in danish, i have a hard time imaging with ‘pikmoji’s trying to imagine what they would look like in this time of #MeeToo... Not so long ago there was a thread about avoiding ‘bad’ names in foreign languages, this name clearly Spawn interesting associations in Denmark :-)
vinodkd 6y ago
I agree, and you can see this even with "simple" diagrams. For example, the Pikchr examples page[1] has a SQLite architecture diagram, and if you click through to the source (like the idea of "click to see source" btw), you'll find lines like this: line invis from 0.25*$margin east of last.sw up last.ht \ "Backend" italic aligned ...which is an invible line used to create a label for the box that's vertically aligned. This is the kind of "toil" that adds up to what you describe. Ideally, this should be a feature of the language itself, something like box "label" valigned nw but you cannot anticipate every bit of adjustment users would need to produce a visually appealing image, since that's subjective. PIC has macros[2] that somewhat make this easier, but as things get larger you'd still have the issues you mention, and you're trading one complexity (hand drawing visually appealing picture) for another (maintaining more complicated code for local visual appeal). I dont know if pikchr supports macros (which are more like functions since troff is a full fledged language, and less like svg symbols afaict) 1: https://pikchr.org/home/doc/trunk/doc/examples.md https://pikchr.org/home/doc/trunk/doc/examples.md 2: http://floppsie.comp.glam.ac.uk/Glamorgan/gaius/web/pic-14.html#14.%20Macros http://floppsie.comp.glam.ac.uk/Glamorgan/gaius/web/pic-14.h...

nattaylor 6y ago

>Any existing Markdown or other wiki rendering engine that can invoke a C-language library should be able to integrate Pikchr quickly and easily. Sounds lightweight! I wonder if that will help with adoption

vinodkd 6y ago
Well, the author's other "single C file dependency" project is somewhat popular I hear, so maybe.
sgbeal 6y ago
> Sounds lightweight! Its public API is literally a single function. You give it pikchr code and it returns a string which contains either an SVG or a description of an error it ran across. (You, the user, can determine which it is by the state of an output parameter (integer pointer).)
- nattaylor 6y ago
  So Pandoc written in Haskell ought to be easy to integrate, right?

hardwaresofton 6y ago

The example listing looks fantastic: https://pikchr.org/home/doc/trunk/doc/examples.md https://pikchr.org/home/doc/trunk/doc/examples.md

octetta 6y ago

Anyone here working on vscode integration for pikchr?