Pikchr: How To Use Pikchr In Fossil Markdown and Fossil Wiki Markup

Embedded Pikchr In Markdown

To include a Pikchr diagram in the middle of a Markdown document in Fossil, simple place the Pikchr script in a fenced code block that has a class of "pikchr". Like this:

   ~~~ pikchr
   arrow; box "Hello!"; arrow
   ~~~

Or like this:

   ``` pikchr
   arrow; box "Hello!"; arrow
   ```

The result appears as follows:

arrow; box "Hello!"; arrow

Image Placement and Source Code Toggle Options

By default, the Pikchr-generated image appears left-justified. If you would prefer that the picture be centered, put the keyword "center" after the class tag. Thus:

   ``` pikchr center
   arrow; box "Hello" "again"; arrow <-
   ```

Results in the following:

arrow; box "Hello" "again"; arrow <-

Pikchrs embedded in Fossil documents can be toggled between their SVG and raw source code forms using the ctrl key and left mouse button, noting that (A) "ctrl" is actually environment-dependent and might be "alt" or the Mac-specific "Command" key, and (B) this feature requires that JavaScript is activated. If the source code should also be revealed by a simple click, add the word "toggle" after the pikchr class tag, as in this click-toggleable example:

arrow ->; box "Click to" "toggle"; arrow <-

Notice that the source code is displayed left-aligned by default. It can be configured to display in the same approximate position as the image by adding the "source-inline" modifier:

arrow ->; box "Click to" "toggle" "(centered)"; arrow <-

The full list of such modifiers, in alphabetical order:

center: center-aligns the image. The default is left-aligned.
float-left and float-right: "float" the image to the left resp. right, such that other content will flow around them.
indent: left-aligns the pikchr, indented by some CSS-specified amount.
source: defaults to source code view instead of SVG view.
source-inline: places the source code view, when revealed, at approximately the same position as the SVG, instead of left-aligned. The source's size may vary wildly from the image's, so this placement is in the same relative position, rather than a precise fit.
toggle: indicates that a single click/tap is required to toggle between SVG and source code views. This is primarily intended to be used in documents which are about learning how to write pikchr code. For consistency, ctrl-click also works on pikchrs tagged with this modifier.

Embedded Pikchr In Fossil Wiki

Fossil supports its own document markup format called (uncreatively) "Fossil Wiki". Fossil Wiki is basically just a safe subset of HTML with a few simple hyperlink, paragraph break, and list formatting enhancements. Fossil Wiki supports something similar to "fenced code blocks" in a special "<verbatim>" tag. All content in between "<verbatim>" and the next "</verbatim>", is displayed exactly as written. Hence, just as fenced code blocks are used to add Pikchr support to Markdown, so too the "<verbatim>" mechanism is used to add Pikchr support to Fossil Wiki.

In Fossil Wiki, Pikchr source text can be enclosed within "<verbatim type="pikchr">" or "<verbatim type="pikchr center"> through the next "</verbatim>" tag. Hence, code like this:

   <verbatim type="pikchr center">
   arrow; ellipse "Hi, Y'all"; arrow
   </verbatim>

Will result in a display like this:

arrow; ellipse "Hi, Y'all"; arrow

Fossil's verbatim format supports the same range of modifiers as the Markdown format, as described above: simply add each modifier in the type attribute after the word pikchr.