Pikchr User Manual

Introduction

This is a guide to generating diagrams using Pikchr, pronounced “picture.” This guide is designed to teach you to use Pikchr in a more accessible manner than you get by reading the grammar specification. We leave discussion of the scope and purpose of Pikchr to a separate document.

For more details and other perspectives, see the following resources:

• Step-by-step example of writing a Pikchr document
• The original Kernighan paper on PIC
• Differences between PIC and Pikchr
• ESR’s documentation on GnuPIC
• DPIC documentation

Running Pikchr Scripts

The design goal of Pikchr is to enable embedded line diagrams in Markdown or other simple markup languages. The details on how to embed Pikchr in Markdown is covered separately. For the purpose of this tutorial, we will only write pure Pikchr scripts without the surrounding markup. To experiment with Pikchr, visit the /pikchrshow page on the website hosting this document (preferably in a separate window). Type in the following script and press the Preview button:

     line; box "Hello," "World!"; arrow

If you do this right, the output should appear as:

So there you go: you’ve created and rendered your first diagram using Pikchr! You will do well to keep that /pikchrshow screen handy, in a separate browser window, so that you can try out scripts as you proceed through this tutorial.

Viewing Pikchr Script Source Code For This Document

For this particular document, you can click on any of the diagrams rendered by Pikchr and the display will convert to showing you the original Pikchr source text. Click again to go back to seeing the rendered diagram.

The click-to-change-view behavior is a property of this one particular document and is not a general capability of Pikchr. On other documents containing Pikchr diagrams that are generated using Fossil you can use Ctrl-click (Option-click on Macs) to toggle the view. That is, click on the diagram while holding down the Ctrl key or the Option key. This is not possible if you are on a tablet or phone, since you don’t have a Ctrl or Option key to hold down there. Other systems might not implement the view-swapping behavior at all. This is a platform-depending feature that is one layer above Pikchr itself.

About Pikchr Scripts

Pikchr is designed to be simple. A Pikchr script is just a sequence of Pikchr statements, separated by either new-lines or semicolons. The “Hello, world!” example above used three statements, a “line”, a “box”, and an “arrow”, each separated by semicolons.

Whitespace (other than newlines) and comments are ignored. Comments in pikchr can be in the style of TCL, C, or C++. That is to say, comments consist of a “#” or “//” and include all characters up to but not including the next new-line, or all text in between “/*” and the first following “*/”. The example script above could be rewritten with each statement on a separate line, and with comments describing what each statement is doing:

    # The first component of the drawing is a line
    line
    // The second component is a box with text "Hello, World!"
    box "Hello," "World!"
    /* Finally an arrow */
    arrow

Remember that new-lines separate statements. If you have a long statement that needs to be split into multiple lines, escape the newline with a backslash character and the new-line will be treated as any other space:

    line
    box \
       "Hello," \
       "World!"
    arrow

So, a Pikchr script is just a list of statements, but what is a statement?

Pikchr Statements

Most statements are descriptions of a single graphic object that becomes part of the diagram. The first token of the statement is the object class-name. The following classes are currently supported:

A statement can be only the class-name and nothing else, but the class-name is usually followed by one or more “attributes”. Attributes are used to modify the appearance of the object, or to position the object relative to prior objects.

So to revisit the “Hello, World” demonstration script above, we see that that script contains three object descriptions:

1. A “line” object with no attributes (meaning that the line is shown with no changes to its default appearance).
2. A “box” object with two string literal attributes. The string literal attributes cause the corresponding strings to be drawn inside the box.
3. An “arrow” object with no attributes.

Layout

By default, objects are stacked beside each other from left to right. The Pikchr layout engine keeps track of the “layout direction”, which can be one of “right”, “down”, “left”, or “up”. The layout direction defaults to “right”, but you can change it using a statement which consists of just the name of the new direction. So, if we insert the “down” statement in front of our test script, like this:

    down
    line
    box  "Hello,"  "World!"
    arrow

Then the objects are stacked moving downward:

Or, you can change the layout direction to “left”:

Or to “up”:

It is common to stack line objects (lines, arrows, splines) against block objects (boxes, circles, ovals, etc.), but this is not required. You can stack a bunch of block objects together. For example:

    box; circle; cylinder

Yields:

More often, you want to put space in between the block objects. The special “move” object exists for that purpose. Consider:

    box; move; circle; move; cylinder

This script creates the same three block objects but with whitespace in between them:

Implementation note: a “move” is really just an invisible “line,” which is why the following script generates the same output as the previous. (Try it!)

    box; line invisible; circle; line invisible; cylinder

Controlling Layout Using Attributes

The automatic stacking of objects is convenient in many cases, but most diagrams will want some objects placed somewhere other than immediately adjacent to their predecessor. For that reason, layout attributes are provided that allow precise placement of objects.

To see how this works, consider the previous example of a box, circle, and cylinder separated by some space. Suppose we want to draw an arrow that goes downward out of the box, then right, then up into the cylinder. The complete script might look something like this:

    box; move; circle; move; cylinder
    arrow from first box.s \
          down 1cm \
          then right until even with first cylinder \
          then to first cylinder.s

This script results in the following diagram:

That is indeed the image we want, but there are a lot of words on that “arrow” statement! Don’t panic, though. It’s actually pretty simple. We’ll take it apart and explain it piece by piece.

First note that the “arrow” statement is broken up into four separate lines of text, with a “\” at the end of the first three lines to prevent the subsequent new-line from prematurely closing the statement. Splitting up the arrow into separate lines this way is purely for human readability. If you are more comfortable putting the whole statement on one line, that is fine too. Pikchr doesn’t care. Just be sure to remember the backslashes if you do split lines!

The attributes on the “arrow” statement describe the path taken by the arrow. The first attribute is “from first box.s”. This “from” attribute specifies where the arrow starts. In this case, it starts at the “s” (or “south”) anchor point of the “first box”. The “first box” part is probably self explanatory. (You can also write it as “1st box” instead of “first box”, and in fact legacy-PIC requires the use of “1st” instead of “first”.) But what is the “.s” part?

Every block object has eight anchor points on its perimeter that are named for compass points, like this:

As you can see, there is also a ninth point in the middle called “.c”. Every block object has these anchor points; you can refer to them when positioning the object itself, or when positioning other objects relative to the block object.

The next phrase on the “arrow” statement is “down 1cm”. As you might guess, this phrase causes the arrow to move downward from its previous position (its starting point) by 1 centimeter. This phrase highlights a key enhancement of Pikchr over PIC, which did everything in inches only. No units were allowed. Pikchr allows you to attach units to measurements, as in this case where it is “1cm”. Internally, Pikchr still keeps track of everything in inches for compatibility with PIC, so the “1cm” token is really just an alternative spelling for the numeric constant “0.39370078740157480316”, which is the inch-equivalent of 1 centimeter. Surely you agree that “1cm” is much easier to read and write! Other units recognized by Pikchr are “px” for pixels, “pt” for points, “pc” for picas, “mm” for millimeters, and of course “in” for inches. Inches are assumed if no units are specified.

Back to our arrow: we have now established a path for the arrow down 1 centimeter from the “.s” anchor of the box. The next phrase is: “then right until even with first cylinder”. You can perhaps guess that this means that the arrow should continue to the right until it is lined up below the first cylinder. You, the diagram designer, don’t know (and don’t really want to know) how far apart the box and the cylinder are, so you can’t tell it exactly how far to go. This phrase is a convenient way of telling Pikchr to “make the line long enough”.

Note that the “first cylinder” part of the “until even with” phrase is actually an abbreviation for “first cylinder.c” - the center of the cylinder. This is what we want. You could also write “first cylinder.s” if you want.

The “until even with” phrase is not found in the original version of PIC. In that system, you would have to do some extra math to figure out the distance for yourself, something like “then right (1st cylinder.s.x - 1st box.s.x)”. We think the “until even with” phrase is easier to use and understand.

The final phrase in the “arrow” statement is “then to first cylinder.s”. This phrase tells the arrow to go from wherever it is at the moment directly to the “.s” anchor of the cylinder.

The Advantage Of Relative Layout

Notice that our sample diagram contains no coordinates and only one hard-coded distance, the “down 1cm” bit in the “arrow” statement. The script is written in such a way that the script-writer does not have to do a lot of distance calculation. The layout compensates automatically.

For example, suppose you come back to this script later and decide you need to insert an ellipse in between the circle and the cylinder. This is easily accomplished:

    box; move; circle; move; ellipse; move; cylinder
    arrow from first box.s \
          down 1cm \
          then right until even with first cylinder \
          then to first cylinder.s

We simply add the ellipse (and an extra “move”) on the first line. Even though the coordinate positions of the objects have adjusted, the description of the arrow that connects the box to the cylinder is not based on coordinates or absolute distances, so it does not have to change at all. Pikchr compensates automatically:

Both PIC and Pikchr allow you to specify hard-coded coordinates and distances when laying out your diagram, but you are encouraged to avoid that approach. Instead, place each new object you create relative to the position of prior objects. Pikchr provides many mechanisms for specifying the location of each object in terms of the locations of its predecessors. With a little study of the syntax options available to you (and discussed further below) you will be generating complex diagrams using Pikchr in no time.

Single-Pass Design

Both Pikchr and PIC operate on a single-pass design. Objects can refer to other objects that occur before them in the script, but not to objects that occur later in the script. Any computations that go into placing an object occur as the object definition is parsed. As soon as the newline or semicolon that terminates the object definition is reached, the size, location, and characteristics of the object are fixed and cannot subsequently be altered. (One exception: sub-objects that are part of a []-container (discussed later) are placed relative to the origin of the container. Their shape and locations relative to each other are fixed, but their final absolute position is not fixed until the []-container itself is fixed.)

The single-pass approach contributes to the conceptual simplicity of Pikchr (and PIC). There is no “solver” that has to work through forward and backward layout constraints to find a solution. This simplicity of design helps to keep Pikchr scripts easy to write and easy to understand.

Labeling Objects

The previous example used the phrases like “first box” and “first cylinder” to refer to particular objects. There are many variations on this naming scheme:

• “previous” ← the previous object regardless of its class
• “last circle” ← the most recently created circle object
• “3rd last oval” ← the antepenultimate oval object
• “17th ellipse” ← the seventeenth ellipse object
• …and so forth

These relative and ordinal references work, but they can be fragile. If you go back later and insert a new object in the stream, you can mess up the counting. Or, for that matter, you might just miscount.

In a complex diagram, it often works better to assign symbolic names to objects, which we call “labels” in Pikchr. A label begins with a capital letter followed by some number of regular ASCII letters, digits or underscores, followed by a colon. This must come immediately before an object, without an intervening newline. Afterwards, the object can be referred to by that label.

Consider how this simplifies our previous example:

    B1:  box; move;
         circle; move;
         ellipse; move;
    C1:  cylinder
         arrow from B1.s \
            down 1cm \
            then right until even with C1 \
            then to C1.s

By giving symbolic names to the box (B1) and cylinder (C1), the arrow path description is simplified. Furthermore, if the ellipse gets changed into another cylinder, the arrow still refers to the correct cylinder.

The indentation of the lines following each symbolic name above is syntactically unimportant: it serves only to improve human readability. Nevertheless, this is typical coding style for Pikchr and PIC before it.

Layout Of Block Objects

For lines (and arrows and splines), you have to specify a path that the line follows, a path that might involve multiple bends and turns. Defining the location of block objects is easier: you just provide a single location to place the object. Ideally, you should place the object relative to some other object, of course.

Let’s say you have a box and you want to position a circle 2 centimeters to the right of that box. You simply use an “at” attribute on the circle to tell it to position itself 2 cm to the right of the box:

  B1: box
      circle at 2cm right of B1

The resulting diagram is:

(We’ve added gray dimension lines purely for illustration. Click the diagram per the instructions above to see that they do not change the example, only add to it.)

The circle is positioned so that its center is 2 centimeters to the right of the center of the box. If what you really wanted is that the left (or west) side of the circle is 2 cm to the right (or east) of the box, then just say so:

  B1: box
  C1: circle with .w at 2cm right of B1.e

Normally an “at” clause will set the center of an object, but if you add a “with” prefix you can specify any other anchor point of the object to be the reference for positioning. The Pikchr script above is saying “make the C1.w point be 2 cm right of B1.e”. And we have:

That’s the whole story behind positioning block objects on a diagram. You just add an attribute of the form:

with reference-point at position

And Pikchr will place the specified reference-point of the object at position. If you omit the “with” clause, the center of the object (“.c”) is used as the reference-point. The power of Pikchr comes from the fact that “position” can be a rather complex expression. The previous example used a relatively simple position of “2cm right of B1.e”. That was sufficient for our simple diagram. More complex diagrams can have more complex position phrases.

    right; box; circle; cylinder

    right; box; circle; cylinder
    dot color red at (0,0)

    right; box; circle; cylinder
    dot color green at 1st box.start
    dot color blue at 1st box.end

    right; box; circle; down; cylinder

    down
    box "Auto-fit text annotation" "as is" fit
    move 50%
    box "Auto-fix text annotation" "with 125% width" fit width 125%

    boxwid = 0; boxht = 0;
    box "Hello";
    move
    box "A longer label" "with multiple lines" "of label text"

   boxwid = 0
   boxht = 0
   box "fully visible"
   box invisible color gray "outline invisible"
   box same solid "outline visible again" fit

Containers

A “container” is a list of one or more objects contained within “[…]”. A container is a collection of one or more objects that looks like a single object to the remainder of the script.

For example:

    A: [
      oval "Hello"
      arrow
      box "World" radius 4px
    ]
    Border: box thin width A.width+0.5in height A.height+0.5in at A.center

The “A” container is composed of an oval, and arrow, and a box with rounded corners. But to the subsequent “Border” box, the “A” container appears to be a single object. The Border box can reference the overall width and height and the center point of the A container in order to size and position itself to enclose the container with a 0.25in border:

A container is mostly useful for adding a border around a collection of objects, as shown above, or adding a caption to a diagram. The following diagram shows what a caption might look like. (Click to see the Pikchr source text.)

In legacy PIC, layout direction changes (the “up”, “down”, “left”, and “right” commands) and variable definitions within a container only affect subsequent statements within the same container. Once the container closes, the prior direction and variable values are restored. Pikchr does not work this way. In Pikchr, layout direction changes and variable definitions that occur within a container continue to be in effect after the container.

Object Stacking Order

Objects are normally drawn in the order in which they are defined. Thus objects that are toward the end of the script that overlap with objects near the beginning will appear to be on top.

Sometimes it is desirable for a later object to appear to be behind an early object. This is useful, for example, when using a box to form a colored background for a group of prior objects. The “behind” attribute with a argument that is the label for any prior object can be added to cause the object that holds the behind attribute to be drawn before the object that the behind attribute references.

Summary And Conclusion

Though based on the decades-old PIC language, Pikchr itself is a relatively new system. However, it has already proven itself to be amazingly useful for helping to illustrate concepts in technical documentation written using Markdown.