pikchr-cmd

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).

Pikchr Source

``` pikchr @usage requote delimiters x-current-color details open
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 | md2html > file.html

Example 2: Intermediate file

$ pikchr < README.md.in > README.md
$ md2html < 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:

bare-svg: 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). svg-only is a synonym for bare-svg.
requote: Output the Pikchr source of this diagram in an indented code block after the compiled diagram. Use the -R command-line option to set this mode for all diagrams.
delimiters: If requoting, include the start and end delimiter lines. The default is to not include the start and end delimiters in a requote.
details: If requoting, put the requoted source into a <details> element. Note that the output is CommonMark compliant, but some older non-CommonMark formatters (such as Markdown.pl) might format <details> incorrectly. The <summary> content is set with the -s command-line option and defaults to “Pikchr Source”. Use the -D command-line option to set this mode for all diagrams.
open: Set the open attribute of the <details> element so that the requoted Pikchr source starts out visible/open/disclosed.
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. Use the -C command-line option to set this experimental mode for all diagrams.

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. For compatibility with the behavior of the latest upstream Pikchr, the default value is style='font-size:initial;'; consider including this style directive if appropriate to any custom setting of this parameter.
-s summary-content
Change the raw HTML content of the <summary> element when requoting diagram source in a <details> element. The default value is Pikchr Source.
-S arbitrary-attributes
Add arbitrary-attributes string to all generated <summary> 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 bare-svg modifier.
-p
Generate plaintext error messages. The default is to output HTML-formatted errors.
-d
Enable “dark mode” in the Pikchr formatter. But consider using -C or modifier x-current-color for a more flexible solution for “dark mode”.
-C
Behave as though the experimental x-current-color modifier (use CSS currentColor instead of rgb(0,0.0) for numeric color value 0) was set on all diagrams. See the description of the x-current-color modifier above for more information.
-R
Requote every diagram’s source, as though the requote modifier was set on all diagrams.
-D
Put all requoted diagram source in <details> elements, as though the details modifier was set on all diagrams.
-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 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.

SVG to PNG Conversion Tool

svg2png.html is a tiny and bare-bones HTML+JavaScript tool you can use to convert an SVG (such as one generated by the pikchr tool) to a Portable Network Graphics (PNG) image file locally using your web browser’s SVG rasterizer, for use in situations or applications that don’t support SVG.

This site is open source. Improve this page.