Fossil  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)
bgcolor = 0x1d2021
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!
bgcolor = 0x1d2021
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.