diff options
Diffstat (limited to 'www/pikchr.md')
| -rw-r--r-- | www/pikchr.md | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/www/pikchr.md b/www/pikchr.md new file mode 100644 index 0000000..09e20d6 --- /dev/null +++ b/www/pikchr.md @@ -0,0 +1,139 @@ +# The Pikchr Diagram Language + +Pikchr (pronounced "picture") is a [PIC][1]-like markup language for creating +diagrams in technical documentation. Source text for Pikchr diagrams +can be embedded directly in either [Markdown][2] or [Fossil Wiki][3]. +Fossil translates the Pikchr source text into SVG which is displayed as +part of the rendered wiki. + +[1]: wikipedia:/wiki/Pic_language +[2]: /md_rules +[3]: /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][4] for an +example of Pikchr in operation. + +[4]: ./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 show the diagram. |