# 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. : wikipedia:/wiki/Pic_language : /md_rules : /wiki_rules For example, this document is written in Markdown. The following is a sample Pikchr diagram: ``` 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 ``` 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. : ./pikchr.md?mimetype=text/plain Fossil allows Pikchr diagrams to appear anywhere that Markdown or Fossil Wiki markup or used, including: * [Embedded documentation](./embeddeddoc.wiki) * Stand-alone wiki pages * [Wiki pages associated with particular branches or check-ins](./wikitheory.wiki#assocwiki) * Check-in comments * [Technical notes](./event.wiki) * [Forum posts](./forum.wiki) * [Bug reports and trouble tickets](./bugtheory.wiki) ## 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"](https://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: * <https://pikchr.org/> 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: ~~~ pikchr toggle arrow; box "Hello" "World!" fit; arrow ~~~ For Markdown, the Pikchr code is put inside of a [fenced code block][fcb]. 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: [fcb]: https://spec.commonmark.org/0.29/#fenced-code-blocks ~~~~~~ ~~~ 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.