Pikchr (pronounced "picture") is a PIC-like markup language for creating diagrams in technical documentation. Pikchr diagrams source text can be embedded directly in either Markdown or Fossil Wiki. Fossil translates the Pikchr source text into SVG which is displayed as part of the rendered wiki.
For example, this document is written in Markdown. The following is a sample Pikchr 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
The diagram above was generated by the following 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
```
See the original Markdown source text of this document for an example of Pikchr in operation.
Fossil allows Pikchr diagrams to appear anywhere that Markdown or Fossil Wiki markup or used, including:
- Embedded documentation
- Stand-alone wiki pages
- Wiki pages associated with particular branches or check-ins
- Check-in comments
- Technical notes
- Forum posts
- Bug reports and trouble tickets
Pikchr Is A Separate Project
Even though the original author of Pikchr is the same as the original creator of Fossil, the sources to the Pikchr formatter are maintained as a separate project named "pikchr.org". Pikchr is a delivered as a single file of C code. The "pikchr.c" file from the Pikchr project is periodically copied into the Fossil source tree. Pikchr is maintained as a project distinct from Fossil so that it can be used independently of Fossil.
Pikchr User Manual And Tutorials
Complete documentation on the Pikchr language can be found on the Pikchr project page:
That website contains a user manual, tutorials, a language specification, a summary of differences between Pikchr and legacy PIC, and it hosts copies of historical PIC documentation.
How To Include Pikchr Diagrams In Fossil Documents
To illustrate how to include Pikchr in Fossil markup, we will use the following one-line Pikchr. Click to see the code:
arrow; box "Hello" "World!" fit; arrow
For Markdown, the Pikchr code is put inside of a fenced code block. A fenced code block is the text in between ``` ... ``` or between ~~~ ... ~~~ using three or more ` or ~ characters. The fenced code block normally displays its content verbatim, but if an "info string" of "pikchr" follows the opening ``` or ~~~, then the content is interpreted as Pikchr script and is replaced by the equivalent SVG. So either of these work:
~~~ pikchr
arrow; box "Hello" "World!" fit; arrow
~~~
``` pikchr
arrow; box "Hello" "World!" fit; arrow
```
For Fossil Wiki, the Pikchr code goes within
<verbatim type="pikchr"> ... </verbatim>. Normally <verbatim>
content is displayed verbatim. The extra type="pikchr" attribute
causes the content to be interpreted as Pikchr and replaced by SVG.
<verbatim type="pikchr">
arrow; box "Hello" "World!" fit; arrow
</verbatim>
Extra Arguments In "Pikchr" Code Blocks
Extra formatting arguments can be included in the fenced code block start
tag, or in the "type=" attribute of <verbatim>, to change the formatting
of the diagram.
indent → The diagram is indented from the left margin.
center → The diagram is centered
toggle → Clicking on the diagram toggles between showing the rendered SVG and the original Pikchr source text. You can always do this by holding down the Ctrl or Alt keys and clicking. The "toggle" option just means you can toggle without holding down any extra keys.
float-left → The diagram is shown at the left margin and text fills in around the diagram.
float-right → The diagram is shown at the right margin and text fills in around the diagram.
source → The display starts out showing the Pikchr source text. The reader must click (or Alt-click or Ctrl-click) to set the diagram.