Pikchr (pronounced "picture") is a PIC-like markup language for diagrams in technical documentation. Pikchr is designed to be embedded in fenced code blocks of Markdown or similar mechanisms of other documentation markup languages.
For example, the diagram:
arrow right 200% "Markdown" "Source" box rad 10px "Markdown" "Formatter" "(markdown.c)" fit arrow right 200% "HTML+SVG" "Output" arrow <-> down 70% from last box.s box same "Pikchr" "Formatter" "(pikchr.c)" fit
Is generated by 7 lines of Markdown:
``` pikchr arrow right 200% "Markdown" "Source" box rad 10px "Markdown" "Formatter" "(markdown.c)" fit arrow right 200% "HTML+SVG" "Output" arrow <-> down 70% from last box.s box same "Pikchr" "Formatter" "(pikchr.c)" fit ```
Pikchr diagrams can appear in:
- Wiki pages
- Tickets and bug reports
- Forum posts
- Check-in comments
- Anywhere else that Markdown or similar markup languages are used
Pikchr diagrams are easy to generate. The language is simple. There is lots of documentation and examples on-line (links below). Anyone who is comfortable using Markdown should be able to pick up Pikchr with minimal extra effort.
Pikchr is safe for use in internet-facing applications. Hostile Pikchr scripts cause no harm (apart from generating ugly diagrams).
Documentation Is A Work In Progress
As of 2020-09-16, the Pikchr code is stable and is in active use. However, documentation is still under development. We are using Pikchr to write the Pikchr documentation (in Markdown), hence it was necessary to deploy Pikchr into a working content management system (Fossil in this case) prior to having complete documentation available. Volunteer assistance is welcomed!
Pikchr Documentation (still under development)
- Pikchr User Manual
- An Example Of How A Pikchr Script Is Written
- Pikchr Language Grammar
- Differences From PIC
- Invoking Pikchr From Markdown
- How To Build Pikchr From Source
Copies Of Historical PIC Documentation
Source-Code License: 0-clause BSD
The Pikchr source code is a self-contained original work. It has no
external dependencies apart from the standard C library and does not
use code taken from the internet or other external sources. All of the Pikchr
source code is released under a zero-clause BSD license. After being
processed using Lemon, the Pikchr source code is a single
file of C89 named "
pikchr.c". These features
are designed to make Pikchr easy to integrate into other systems.