Fossil

The Pikchr Diagram Language
Login

The Pikchr Diagram Language

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:

Markdown Source Markdown Formatter (markdown.c) HTML+SVG Output Pikchr Formatter (pikchr.c) 
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:

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:

Hello World! 
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.