|
1
|
# The Pikchr Diagram Language |
|
2
|
|
|
3
|
Pikchr (pronounced "picture") is a [PIC][1]-like markup language for creating |
|
4
|
diagrams in technical documentation. Source text for Pikchr diagrams |
|
5
|
can be embedded directly in either [Markdown][2] or [Fossil Wiki][3]. |
|
6
|
Fossil translates the Pikchr source text into SVG which is displayed as |
|
7
|
part of the rendered wiki. |
|
8
|
|
|
9
|
[1]: wikipedia:/wiki/Pic_language |
|
10
|
[2]: /md_rules |
|
11
|
[3]: /wiki_rules |
|
12
|
|
|
13
|
For example, this document is written in Markdown. The following |
|
14
|
is a sample Pikchr diagram: |
|
15
|
|
|
16
|
``` pikchr |
|
17
|
arrow right 200% "Markdown" "Source" |
|
18
|
box rad 10px "Markdown" "Formatter" "(markdown.c)" fit |
|
19
|
arrow right 200% "HTML+SVG" "Output" |
|
20
|
arrow <-> down 70% from last box.s |
|
21
|
box same "Pikchr" "Formatter" "(pikchr.c)" fit |
|
22
|
``` |
|
23
|
|
|
24
|
The diagram above was generated by the following lines of Markdown: |
|
25
|
|
|
26
|
~~~~~ |
|
27
|
``` pikchr |
|
28
|
arrow right 200% "Markdown" "Source" |
|
29
|
box rad 10px "Markdown" "Formatter" "(markdown.c)" fit |
|
30
|
arrow right 200% "HTML+SVG" "Output" |
|
31
|
arrow <-> down 70% from last box.s |
|
32
|
box same "Pikchr" "Formatter" "(pikchr.c)" fit |
|
33
|
``` |
|
34
|
~~~~~ |
|
35
|
|
|
36
|
See the [original Markdown source text of this document][4] for an |
|
37
|
example of Pikchr in operation. |
|
38
|
|
|
39
|
[4]: ./pikchr.md?mimetype=text/plain |
|
40
|
|
|
41
|
Fossil allows Pikchr diagrams to appear anywhere that Markdown or |
|
42
|
Fossil Wiki markup or used, including: |
|
43
|
|
|
44
|
* [Embedded documentation](./embeddeddoc.wiki) |
|
45
|
* Stand-alone wiki pages |
|
46
|
* [Wiki pages associated with particular branches or check-ins](./wikitheory.wiki#assocwiki) |
|
47
|
* Check-in comments |
|
48
|
* [Technical notes](./event.wiki) |
|
49
|
* [Forum posts](./forum.wiki) |
|
50
|
* [Bug reports and trouble tickets](./bugtheory.wiki) |
|
51
|
|
|
52
|
## Pikchr Is A Separate Project |
|
53
|
|
|
54
|
Even though the original author of Pikchr is the same as the original |
|
55
|
creator of Fossil, the sources to the Pikchr formatter are maintained |
|
56
|
as a [separate project named "pikchr.org"](https://pikchr.org). |
|
57
|
Pikchr is a delivered as a single file of C code. The "pikchr.c" file |
|
58
|
from the Pikchr project is periodically copied into the Fossil source |
|
59
|
tree. Pikchr is maintained as a project distinct from Fossil so that it |
|
60
|
can be used independently of Fossil. |
|
61
|
|
|
62
|
### Pikchr User Manual And Tutorials |
|
63
|
|
|
64
|
Complete documentation on the Pikchr language can be found on the |
|
65
|
Pikchr project page: |
|
66
|
|
|
67
|
* <https://pikchr.org/> |
|
68
|
|
|
69
|
That website contains a user manual, tutorials, a language specification, |
|
70
|
a summary of differences between Pikchr and legacy PIC, |
|
71
|
and it hosts copies of historical PIC documentation. |
|
72
|
|
|
73
|
## How To Include Pikchr Diagrams In Fossil Documents |
|
74
|
|
|
75
|
To illustrate how to include Pikchr in Fossil markup, we will use the |
|
76
|
following one-line Pikchr. Click to see the code: |
|
77
|
|
|
78
|
~~~ pikchr toggle |
|
79
|
arrow; box "Hello" "World!" fit; arrow |
|
80
|
~~~ |
|
81
|
|
|
82
|
For Markdown, the Pikchr code is put inside of a |
|
83
|
[fenced code block][fcb]. A fenced code block is the text in between |
|
84
|
``` ... ``` or between |
|
85
|
~~~ ... ~~~ using three or |
|
86
|
more ` or ~ characters. The fenced code block normally |
|
87
|
displays its content verbatim, but if an "info string" of "pikchr" |
|
88
|
follows the opening ``` or ~~~, then the |
|
89
|
content is interpreted as Pikchr script and is replaced by the |
|
90
|
equivalent SVG. |
|
91
|
So either of these work: |
|
92
|
|
|
93
|
[fcb]: https://spec.commonmark.org/0.29/#fenced-code-blocks |
|
94
|
|
|
95
|
~~~~~~ |
|
96
|
~~~ pikchr |
|
97
|
arrow; box "Hello" "World!" fit; arrow |
|
98
|
~~~ |
|
99
|
|
|
100
|
``` pikchr |
|
101
|
arrow; box "Hello" "World!" fit; arrow |
|
102
|
``` |
|
103
|
~~~~~~ |
|
104
|
|
|
105
|
For Fossil Wiki, the Pikchr code goes within |
|
106
|
`<verbatim type="pikchr"> ... </verbatim>`. Normally `<verbatim>` |
|
107
|
content is displayed verbatim. The extra `type="pikchr"` attribute |
|
108
|
causes the content to be interpreted as Pikchr and replaced by SVG. |
|
109
|
|
|
110
|
~~~~~~ |
|
111
|
<verbatim type="pikchr"> |
|
112
|
arrow; box "Hello" "World!" fit; arrow |
|
113
|
</verbatim> |
|
114
|
~~~~~~ |
|
115
|
|
|
116
|
## Extra Arguments In "Pikchr" Code Blocks |
|
117
|
|
|
118
|
Extra formatting arguments can be included in the fenced code block start |
|
119
|
tag, or in the "`type=`" attribute of `<verbatim>`, to change the formatting |
|
120
|
of the diagram. |
|
121
|
|
|
122
|
* **indent** → The diagram is indented from the left margin. |
|
123
|
|
|
124
|
* **center** → The diagram is centered |
|
125
|
|
|
126
|
* **toggle** → Clicking on the diagram toggles between showing |
|
127
|
the rendered SVG and the original Pikchr source text. You can always |
|
128
|
do this by holding down the Ctrl or Alt keys and clicking. The |
|
129
|
"toggle" option just means you can toggle without holding down any |
|
130
|
extra keys. |
|
131
|
|
|
132
|
* **float-left** → The diagram is shown at the left margin and |
|
133
|
text fills in around the diagram. |
|
134
|
|
|
135
|
* **float-right** → The diagram is shown at the right margin and |
|
136
|
text fills in around the diagram. |
|
137
|
|
|
138
|
* **source** → The display starts out showing the Pikchr source text. |
|
139
|
The reader must click (or Alt-click or Ctrl-click) to show the diagram. |
|
140
|
|