Pikchr

Pikchr (pronounced "picture") is a [PIC][1]-like markup
language for diagrams in technical documentation.  Pikchr is
designed to be embedded in [fenced code blocks][2] of
Markdown or similar mechanisms of other documentation markup languages.

[1]: https://en.wikipedia.org/wiki/Pic_language
[2]: https://spec.commonmark.org/0.29/#fenced-code-blocks

For example, the diagram:

``` pikchr
arrow right 200% "Markdown" "Source"
box rad 10px "Markdown" "Formatter" "(markdown.c)" fit
arrow right 200% "HTML+SVG" "Output"
arrow <-> down 70% from last box.s
box same "Pikchr" "Formatter" "(pikchr.c)" fit
```

Is generated by 7 lines of Markdown:

~~~~~~
   ``` pikchr
   arrow right 200% "Markdown" "Source"
   box rad 10px "Markdown" "Formatter" "(markdown.c)" fit
   arrow right 200% "HTML+SVG" "Output"
   arrow <-> down 70% from last box.s
   box same "Pikchr" "Formatter" "(pikchr.c)" fit
   ```
~~~~~~

Pikchr diagrams can appear in:

  *  Documentation
  *  Wiki pages
  *  Tickets and bug reports
  *  Forum posts
  *  Check-in comments
  *  Anywhere else that Markdown or similar markup languages are used

Pikchr diagrams are easy to generate.  The language is simple.
There is lots of documentation and examples on-line (links below).
Anyone who is comfortable using Markdown should be able to pick up Pikchr
with minimal extra effort.

Pikchr is safe for use in internet-facing applications.  Hostile
Pikchr scripts cause no harm (apart from generating ugly diagrams).

## Demos

  *  [Example Pikchr Scripts](./doc/examples.md)
     ([light-mode](/doc/trunk/doc/examples.md?skin=default&once) or
      [dark-mode](/doc/trunk/doc/examples.md?skin=darkmode&once))
  *  [](/pikchrshow) &larr; Enter Pikchr text and see the result on-line
  *  [Source text for this page](./homepage.md?mimetype=text/plain)

## Pikchr Documentation

  *  [Purpose And Scope Of Pikchr](./doc/purpose.md)
  *  [Pikchr User Manual](./doc/userman.md)
  *  [An Example Of How A Pikchr Script Is Written](./doc/teardown01.md)
  *  [Pikchr Language Spec](./doc/grammar.md)
  *  [Differences From PIC](./doc/differences.md)
  *  [Invoking Pikchr From Markdown](./doc/usepikchr.md)
  *  [How To Build Pikchr From Source](./doc/build.md)
  *  [Use Case: SQLite Syntax Diagrams](./doc/sqlitesyntax.md)

## Copies Of Historical PIC Documentation

  *  [BWK paper on the original PIC](/uv/pic.pdf)
  *  [DPIC Documentation](/uv/dpic-doc.pdf)
  *  [ESR GnuPIC Docs](/uv/gpic.pdf)

## Source Code

  *  [Download](./doc/download.md)
  *  [How To Build Pikchr From Source](./doc/build.md)
  *  [How To Integrate Pikchr Into Other Applications][integ]


## Source-Code License: 0-clause BSD

The Pikchr source code is a self-contained original work.  It has no
external dependencies apart from the standard C library and does not
use code taken from the internet or other external sources.  All of the Pikchr
source code is released under a [zero-clause BSD license][0BSD].  After being
processed using [Lemon][lemon], the Pikchr source code is a single
file of C89 named "`pikchr.c`".  These features
are designed to make Pikchr [easy to integrate into other systems][integ].

[0BSD]: https://spdx.org/licenses/0BSD.html
[lemon]: https://www.sqlite.org/lemon.html
[integ]: doc/integrate.md