Pikchr Command-Line Tool

This preprocessor tool reads text from the standard input, replacing suitably-delimited Pikchr (a PIC-like diagram language) diagram descriptions with inline Scalable Vector Graphics (SVG), and writes to the standard output. It’s intended to be composed with your favorite Markdown processor, but can be used standalone or with other markup languages or workflows too.

This tool uses the C reference implementation of Pikchr by Richard Hipp which is included here for convenience (as permitted by its generous license).

Markdown+Pikchr Source pikchr Preprocessor (main.c) Markdown+SVG Intermediate Any Markdown Formatter HTML+SVG Output  C API Pikchr Formatter (pikchr.c)

``` pikchr @usage requote delimiters x-current-color
arrow right 225% "Markdown+Pikchr" "Source"
Tool: box rad 5px "pikchr" mono "Preprocessor" "(main.c)" mono fit
arrow same "Markdown+SVG" "Intermediate"
box same "Any Markdown" "Formatter" fit height Tool.height
arrow same "HTML+SVG" "Output"
arrow <-> down from Tool.south " C API" ljust
box same "Pikchr" "Formatter" "(pikchr.c)" mono fit
```

GitHub doesn’t allow inline SVGs, so here’s the above diagram as an external image reference (see Example 3 below):

Example 1: Pipeline

$ pikchr < file.md | Markdown.pl > file.html

Example 2: Intermediate file

$ pikchr < README.md.in > README.md
$ Markdown.pl < README.md > README.html

Example 3: Compile the diagram in README.md.in that is tagged with modifier “@usage” to a separate SVG file called usage.svg

$ pikchr -q -b -N @usage < README.md.in > usage.svg

Delimiters

A Pikchr diagram starts with a line beginning with any of the following strings without indentation:

• Three or more consecutive GRAVE ACCENT backtick (`) characters, optional whitespace, the characters pikchr, and whitespace or end-of-line; for example
  • ```` pikchr
• Three or more consecutive TILDE (~) characters, optional whitespace, the characters pikchr, and whitespace or end-of-line; for example
  • ~~~pikchr
• The three characters .PS and whitespace or end-of-line (that is, the traditional PIC start delimiter)
  • .PS

and ends with the next line that is any of the following strings without indentation (or the end of the file):

• Three or more consecutive backtick characters and optional whitespace; for example
  • ```
• Three or more consecutive TILDE characters and optional whitespace; for example
  • ~~~~
• The three characters .PE and optional whitespace (that is, the traditional PIC end delimiter)
  • .PE

Anything not between a pair of start and end delimiters is copied to the standard output unchanged.

Note that generic Markdown fenced code blocks can begin with three or more consecutive TILDE (~) or backtick (`) characters optionally indented by up to three spaces, and continue to a fence of the same type (tilde or backtick), optionally indented by up to three spaces, and at least as long. For simplicity, when looking for Pikchr diagrams, this tool doesn’t require the end delimiter to be of the same type or to be at least as long as the start delimiter. This tool doesn’t recognize indented start and end delimiters in order to easily accommodate displaying Pikchr code itself by using an indented fenced code block.

Start Delimiter Modifiers

Any number of whitespace-delimited modifier strings can follow the start delimiter prefix on the same line. Modifiers can change the behavior of the Pikchr formatter for just that diagram. Unrecognized modifiers are ignored, but can be matched by the -N command-line option (use -h to see all of the available options). The following modifiers are recognized:

• svg-only: Output the <svg> tag without wrapping it in a <div>. By default (unless command-line option -b is given) each diagram is enclosed in a <div> styled with max-width set to the diagram’s width, so it won’t expand to the width of the page (which is usually not desired).
• requote: Output the Pikchr source of this diagram in an indented code block after the compiled diagram.
• delimiters: If requoting, include the start and end delimiter lines. The default is to not include the start and end delimiters in a requote.
• x-current-color: Experimental, output CSS currentColor instead of rgb(0,0,0) for numeric color value 0 (black, the default marking color in diagrams). The diagram will be painted in the SVG element’s inherited foreground color instead of the default black, which may enable naturally adapting to different page themes or dark mode. Note that only color value 0 is affected. To force black, set the color to a positive number less than 0.5.

Building

$ git clone https://github.com/zenomt/pikchr-cmd
$ cd pikchr-cmd
$ make all
$ ./pikchr -h

Command Line Options

The following command line options are recognized:

• -c aClass
  Add attribute class="aClass" to all generated <svg> tags.
• -a arbitrary-attributes
  Add arbitrary-attributes string to all generated <svg> tags.
• -b
  “Bare SVG mode”: don’t enclose generated SVG elements in a <div>. By default a <div> wrapper is used to apply a max-width style to the diagram to keep it from expanding to the full window width. Use this option to manually style the diagram’s displayed size with your own DIV or when generating a standalone SVG file. This can also be enabled per-diagram with the svg-only modifier.
• -p
  Generate plaintext error messages. The default is to output HTML-formatted errors.
• -d
  Enable “dark mode” in the Pikchr formatter.
• -q
  “Quiet mode”: don’t copy non-diagram input to the output. Use this option when generating a standalone SVG file.
• -Q
  Remove all Pikchr diagrams from the output.
• -n num
  Only translate diagram number num to SVG. Diagrams are numbered starting from 1. This is usually used along with -q and -b when generating a standalone SVG file. Note that this method is brittle, consider using -N instead.
• -N mod-string
  Only translate diagrams that have mod-string as one of their start delimiter modifiers. This is usually used along with -q and -b when generating a standalone SVG file (in which case mod-string should be unique).
• -h
  Show the help message describing these options and quit.