Pikchr

# Circle objects

A circle is defined by one of:

   *  `radius`
   *  `diameter`
   *  `width`
   *  `height`

Only one of these values can set for any particular circle; the others 
are determined automatically by the first.
The default radius is value of the "`circlerad`" variable.


~~~~ pikchr indent
A: circle thick rad 120%
line thin color gray left 70% from 2mm left of (A.w,A.n)

attack based on deeply nested macros.  Each time a macro is invoked, it
is rescanned and all of the tokens within the macro are added to the
running total.  Without the token limit, an attacker could devise a
script that contained nested macros that generates billions and billions
of glyphs in the final image, consuming large amounts of memory and
CPU time in the process.

The token limit is determined by the `PIKCHR_TOKEN_LIMIT` preprocessor
macro in the source code.  The default token limit is 100000, which
should be more than enough for any reasonable script.  The limit
can be increased (or decreased) at compile-time by redefining that
macro.

## Discontinued Features

  *  <https://pikchr.org/home/tarball/trunk/pikchr.tar.gz>
  *  <https://pikchr.org/home/zip/trunk/pikchr.zip>

With the complete source tree on your local machine, you can run
"`make test`" to build and test Pikchr.

## Clone the Fossil Repository

Pikchr uses [Fossil](https://fossil-scm.org/home) for version control.
You can clone the entire repository (which includes everything on
this website, including all the documentation and test cases) as follows:

  *  [Install Fossil](https://fossil-scm.org/home/uv/download.html)
      if you haven't done so already

  *  `fossil ui`

See the [Fossil documentation][fossil-doc] for more information on how
manage a Fossil repository.

[fossil-doc]: https://fossil-scm.org/home/doc/trunk/www/permutedindex.html

## Clone the GitHub Mirror

There is a (read-only) mirror of this repository

[on GitHub](https://github.com/drhsqlite/pikchr).

# Ellipse Objects

The shape of an ellipse is determined solely by its height and width.

~~~~ pikchr indent
A: ellipse thick
line thin color gray left 70% from 2mm left of (A.w,A.n)
line same from 2mm left of (A.w,A.s)
text "height" at (7/8<previous.start,previous.end>,1/2<1st line,2ndline>)
line thin color gray from previous text.n up until even with 1st line ->
line thin color gray from previous text.s down until even with 2nd line ->
X1: line thin color gray down 50% from 2mm below (A.w,A.s)
X2: line thin color gray down 50% from 2mm below (A.e,A.s)
text "width" at (1/2<X1,X2>,6/8<X1.start,X1.end>)
line thin color gray from previous text.w left until even with X1 ->
line thin color gray from previous text.e right until even with X2 ->
~~~~

Unlike a circle, ellipses have no radius, but if the

width and height are equal, it is visually identical to a circle.


## Boundary Points

~~~~ pikchr indent
A: ellipse thin
dot ".c" below at A
dot ".n" above at A.n
dot " .ne" ljust above at A.ne
dot " .e" ljust at A.e
dot " .se" ljust below at A.se
dot ".s" below at A.s
dot ".sw " rjust below at A.sw
dot ".w " rjust at A.w
dot ".nw " rjust above at A.nw
~~~~

# File objects

A "file" is a stylized image of a piece of paper with the upper right
corner folded over.  Similar images are commonly used to represent "files".
The shape of a file object is defined by its width, height, and radius.
The radius is the height and width of the folded corner.  The default values
for height, radius, and width are controlled by variables
"`fileht`", "`filerad`", and "`filewid`".

~~~~ pikchr indent
A: file thick rad 100%
line thin color gray left 70% from 2mm left of (A.w,A.n)
line same from 2mm left of (A.w,A.s)
text "height" at (7/8<previous.start,previous.end>,1/2<1st line,2ndline>)

# line-length

A *line-length* is an expression that specifies how long to draw a
line segment.  The value can be either absolute (ex: "`1.2cm`", 
"`.5in`", "`0.5*circlerad`", and so forth) or it can be a percentage value
(ex: "`85%`").

  * *expr*
  * *expr* **%**

If the percentage value is used, the basis is usually the
value stored in the "`linewid`" variable.  However, for a case of
either:

  * **up** *expr* **%**
  * **down** *expr* **%**

…then the percentage refers to the current "`lineht`" value instead.  The
"`linewid`" value is always used for headings even if the heading
is "`0`" or "`180`" or "`north`" or "`south`".

In most cases it does not matter whether "`linewid`" or "`lineht`"
gets used for the percentage basis since both variables have the
same initial default of 0.5in.

# path-attribute

A *path-attribute* is used to provide the origin and direction of a line
object, that being an arc, arrow, line, move, or spline.  It is an error
to use a *path-attribute* on a block object, that being a box, circle,
cylinder, dot, ellipse, file, oval, or text.

There are seven forms:

  *  **from** *position*
  *  **then**? **to** *position*
  *  **then**? **go**? *direction* *distance*?
  *  **then**? **go**? *direction* **until**? **even with** *place*

"Manhattan geometry" (lines are axis-aligned) or that negotiate around
obstacles.  The phrase:

>  go *direction* until even with *position*

Means to continue the line in the specified *direction* until the
coordinate being changed matches the corresponding coordinate in
*position*. If the line is going up or down, then it continues until
the Y coordinate matches the Y coordinate of *position*.  If the line
is going left or right, then it continues until
the X coordinate matches the X coordinate of *position*.

For example, suppose in the diagram below that we want to draw an arrow 
that begins on Origin.s and ends on Destination.s but goes around
the Obstacle oval, clearing it by at least one centimeter.

| bottommargin  | Extra border space added to the bottom of the diagram      |
| fgcolor       | Use this foreground color in place of black                |
| fontscale     | Scale factor applied to the font size of text              |
| layer         | The default layer for all subsequent objects               |
| leftmargin    | Extra border space added to the left of the diagram        |
| margin        | Extra border space added to all four sides of the diagram  |
| rightmargin   | Extra border space added to the right side of the diagram  |
| topmargin     | Extra border space added to the top side of the diagram    |


The "VARIABLE *assignment-op* *expr*" syntax is able to modify the value
of built-in variables, or create new variables.  In legacy-PIC, the only
*assignment-op* was "`=`".  Pikchr adds "`+=`", "`-=`", "`*=`", and
"`/=`" to make it easier to scale existing variables up or down.

   then to last oval.e ->
line from last oval.w left $r then up until even with 2nd last oval \
   then left 2*$r ->
~~~~~

## Whitespace

Whitespace other than a newline is ignored.  If a backslash is followed
by one or more whitespace characters ending in a newline, then the
backslash and all of the spaces that follow, including the newline,
are considered whitespace.  Thus, a backslash at the end of a line
causes a statement to continue onto the next line.

## Comments

by adjusting some variable settings.

## Lines 04 and 05 - establishing the prototype node circle

Line 04 creates a circle sized to fit its label "C0".  We want
all the circles in this diagram to be the same size, so after sizing
the first one to fit the text, line 05 sets the new default circle radius
for all subsequent circles to be the same as the first circle.  This
not only saves us from having to add a "fit" on every "circle" call, it means
all circles will be of a uniform size despite containing
varying amounts of text.

## Lines 06 through 13 - the bottom row of nodes

After establishing the initial diagram node, lines 06 through 13 create

Because these node labels include "prime" marks (`'`), you cannot use
them as object labels as we could for the corresponding C3 and C5
nodes. Therefore, the nodes of this second branch are given
explicit labels "C3P" and "C5P".  Do not be bashful about adding
labels to objects.  The use of labels often makes the script much
easier to read and maintain.

## Lines 22 through 26 - background color for trunk

Lines 22 through 26 implement a single box object that provides background
color for the trunk.  Note the use of backslash ("`\`") to continue the
definition of this object across multiple lines.  It is not required to
break up the definition of the box across multiple lines; it
merely aids human
understanding.  Pikchr does not care how long your source lines are.

this box before it paints the C0 circle, so that the background color
box occurs in the background rather than on top of the graph.
Try commenting out the "`behind C0`" to see what happens!

Finally, line 26 changes the fill color for the box to a light shade
of blue and the border to be thin and gray.

## Lines 27 through 29 - background color for the branches

Lines 27 through 29 create a second box to provide background color
to the upper branches.  The second box definition begins with the
keyword "`same`".  The "`same`" means that all of the settings to
the new box are initialized to values from the previous box.  That
means we don't have to set the height, or set "`behind C0`" or
"`thin`" or "`color gray`".  All those attributes are inherited.

Line 28 positions the second box.  The southeast (.se) corner of
the second box is set to align with the northeast (.ne) corner of
the previous box.  This causes the two boxes to be flush right
and stacked directly on top of each other.

Line 29 adjusts the background color to a darker shade of blue.

## Lines 30 and 31 - labeling the branches

Lines 30 and 31 create a pair of text objects to identify the two
branches depicted in the diagram.  

# Summary

A 31-line Pikchr script might look intimidating at first glance, but

a practical and accessible tutorial on using Pikchr.

[gram]: ./grammar.md

# Running Pikchr Scripts <a id="running"></a>

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][embed].  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:
<a id="firstdemo"></a>

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 <a id="about"></a>

Pikchr is designed to be simple.  A Pikchr script is

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

  circle "C1" fit
  circle "C0" at C1+(2.5cm,-0.3cm) fit
  arrow from C1 to C0 "aligned" aligned above <- chop
~~~~

### Adjusting The Font Size <a id="font-size"></a>

The "`big`" and "`small`" attributes cause the text to be a little
larger or a little smaller, respectively.  Two "`big`" attributes cause
the text to be larger still; similarly, two "`small`" attributes make it
smaller-than-small. Text size does not increase or decrease beyond two
"`big`" or "`small`" keywords.

~~~~ pikchr indent toggle
  box "small small" small small "small" small \
    "(normal)" italic \
    "big" big "big big" big big ht 200%
~~~~