Pikchr – PIC-like markup language for diagrams in technical documentation
pikchr.org
pikchr.org
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.
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, for use in copy/pasting into one's own pikchrs.
[^1] = https://pikchr.org/home/pikchrshow (full disclosure: i added that feature fossil)
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 :-)
line invis from 0.25*$margin east of last.sw up last.ht \
"Backend" italic aligned
box "label" valigned nw
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 2: http://floppsie.comp.glam.ac.uk/Glamorgan/gaius/web/pic-14.h...
It is difficult to find the right balance between a simple language that requires "toil" and a less toilsome language that is also more complex and requires more effort to learn and master. I'm very open to new ideas of how to make the Pikchr language less toilsome without a corresponding increase in complexity. Expect improvements to occur. Your suggestions are welcomed
I envision Pikchr operating in the same nitch as Markdown. (Indeed, Pikchr was originally designed to augment Markdown-based documentation.) An artificial language like PIC/Pikchr is always going to have a steeper learning curve than a GUI diagram drawing tool, just as Markdown documents are always going to be a barrier to entry for pointy-clicky people who prefer MS-Word or Google-Docs. And yet, Markdown persists and even flourishes. Why is that? If point-and-click really is so much better, why are there so many Markdown technical documents out there?
A key advantage of Markdown, which helps it thrive in a point-and-click world, is that it is very simple to learn and requires no proprietary tools. Pikchr is not as simple, though it is simpler (I think) than any other artificial language for graphics that I have encountered, and I've tried to make the Pikchr code as accessible and as easy to integrate as I know how. I'm on a mission to make Pikchr simpler still. Your feedback on how to do that is appreciated.
I've generated plenty of diagrams in Graphviz where everything was great except for a poorly-placed node or two, and I think this sort of two-part solution could provide the best of both worlds. (Or, at least, it would be a fun R&D project.)
The parallel to Markdown is apt, since it too does not do everything HTML does, and that's good (tm). The use of "same" and "last" also forces a locality that would be lost if the diagram were large.
I gave an example of a box syntax that allowed defining a label aligned vertically, but I did so to illustrate that while such an extension could be done, the library author could not possibly imagine all such attributes that users might want.
The default answer to this is an extension mechanism, i.e, you allow users to create their own primitives, but that might be overkill for the pikchr use case, and would possibly require going past the "single pass through lemon produces a c file that can be integrated into any c project" model.
The other idea - stolen from Markdown - would be to "fall through" to SVG at will by allowing svg syntax as also being valid in pikchr, but I dont know that SVG is as forgiving as HTML to do that.
Sounds lightweight! I wonder if that will help with adoption
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).)
Perhaps pikchr is more flexible but more verbose?
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.