How Pikchr Generates the SQLite Syntax Diagrams

Beginning with SQLite version 3.34.0, the graphical syntax diagrams in the SQLite documentation are SVGs generated using Pikchr. In prior versions of SQLite, the diagrams were GIF images generated using a fiddly processing chain based on Tcl/Tk, Ghostscript, and ImageMagick.

Advantages to the New Approach

How It Works

The SQLite documentation is generated using a Tcl script from source documents. The script evaluates Tcl code embedded into the source files between <tcl>...</tcl> tags, extends HTML with enhanced hyperlinks and formatting features, and outputs the result as standard HTML.

Each syntax diagram is a file in the art/syntax/ subdirectory of the documentation source repository. You can click on any of the Pikchr source files to see the corresponding diagram. Click on the "Text" submenu option to see the original Pikchr source text rather than the rendered SVG.

Pikchr as a Tcl Extension

The pikchr.c source file can be compiled into a Tcl extension by adding the -DPIKCHR_TCL compile-time option. As a Tcl extension, Pikchr provides a single new Tcl command named "pikchr" which takes a single argument: the Pikchr source text. The pikchr command returns a Tcl list of three elements which are:

  1. The SVG output text
  2. The width of the output in pixels
  3. The height of the output in pixels

As with ordinary Pikchr, a negative width is returned if the input text contains an error, and the output text is the error message.

Automatic Insertion of Diagrams into Documentation

Within the SQLite documentation source text, markup of the following form causes the named Pikchr syntax diagram to be loaded, converted into SVG, and the output SVG added to the documentation under construction:

   RecursiveBubbleDiagram expr

The RecursiveBubbleDiagram Tcl procedure uses the "pikchr" Tcl command to convert the Pikchr source text into SVG and inserts that SVG. The command also looks for other diagrams that are referenced by that diagram and loads them as well, together with appropriate JavaScript to cause the sub-diagrams to be initially hidden, but to expand when the reader clicks on the appropriate links.