1# Pikchr Examples
2
3## Usage Note
4
5~~~ pikchr toggle
6box color red wid 2.6in \
7    "Click on any diagram on this page" big \
8    "to see the Pikchr source text" big
9
10~~~
11
12## How To Build Pikchr
13
14~~~ pikchr toggle
15            filewid *= 1.2
16  Src:      file "pikchr.y"; move
17  LemonSrc: file "lemon.c"; move
18  Lempar:   file "lempar.c"; move
19            arrow down from LemonSrc.s
20  CC1:      oval "C-Compiler" ht 50%
21            arrow " generates" ljust above
22  Lemon:    oval "lemon" ht 50%
23            arrow from Src chop down until even with CC1 \
24              then to Lemon.nw rad 20px
25            "Pikchr source " rjust "code input " rjust \
26              at 2nd vertex of previous
27            arrow from Lempar chop down until even with CC1 \
28              then to Lemon.ne rad 20px
29            " parser template" ljust " resource file" ljust \
30              at 2nd vertex of previous
31  PikSrc:   file "pikchr.c" with .n at lineht below Lemon.s
32            arrow from Lemon to PikSrc chop
33            arrow down from PikSrc.s
34  CC2:      oval "C-Compiler" ht 50%
35            arrow
36  Out:      file "pikchr.o" "or" "pikchr.exe" wid 110%
37~~~
38
39## SQLite Architecture Diagram
40
41Inspired by the JPG image seen at <https://www.sqlite.org/arch.html>
42
43~~~ pikchr toggle
44    lineht *= 0.4
45    $margin = lineht*2.5
46    scale = 0.75
47    fontscale = 1.1
48    charht *= 1.15
49    down
50In: box "Interface" wid 150% ht 75% fill white
51    arrow
52CP: box same "SQL Command" "Processor"
53    arrow
54VM: box same "Virtual Machine"
55    arrow down 1.25*$margin
56BT: box same "B-Tree"
57    arrow
58    box same "Pager"
59    arrow
60OS: box same "OS Interface"
61    box same with .w at 1.25*$margin east of 1st box.e "Tokenizer"
62    arrow
63    box same "Parser"
64    arrow
65CG: box same ht 200% "Code" "Generator"
66UT: box same as 1st box at (Tokenizer,Pager) "Utilities"
67    move lineht
68TC: box same "Test Code"
69    arrow from CP to 1/4<Tokenizer.sw,Tokenizer.nw> chop
70    arrow from 1/3<CG.nw,CG.sw> to CP chop
71
72    box ht (In.n.y-VM.s.y)+$margin wid In.wid+$margin \
73       at CP fill 0xd8ecd0 behind In
74    line invis from 0.25*$margin east of last.sw up last.ht \
75        "Core" italic aligned
76
77    box ht (BT.n.y-OS.s.y)+$margin wid In.wid+$margin \
78       at Pager fill 0xd0ece8 behind In
79    line invis from 0.25*$margin east of last.sw up last.ht \
80       "Backend" italic aligned
81
82    box ht (Tokenizer.n.y-CG.s.y)+$margin wid In.wid+$margin \
83       at 1/2<Tokenizer.n,CG.s> fill 0xe8d8d0 behind In
84    line invis from 0.25*$margin west of last.se up last.ht \
85       "SQL Compiler" italic aligned
86
87    box ht (UT.n.y-TC.s.y)+$margin wid In.wid+$margin \
88       at 1/2<UT,TC> fill 0xe0ecc8 behind In
89    line invis from 0.25*$margin west of last.se up last.ht \
90      "Accessories" italic aligned
91~~~
92
93## Syntax diagrams
94
95~~~ pikchr toggle
96$r = 0.2in
97linerad = 0.75*$r
98linewid = 0.25
99
100# Start and end blocks
101#
102box "element" bold fit
103line down 50% from last box.sw
104dot rad 250% color black
105X0: last.e + (0.3,0)
106arrow from last dot to X0
107move right 3.9in
108box wid 5% ht 25% fill black
109X9: last.w - (0.3,0)
110arrow from X9 to last box.w
111
112
113# The main rule that goes straight through from start to finish
114#
115box "object-definition" italic fit at 11/16 way between X0 and X9
116arrow to X9
117arrow from X0 to last box.w
118
119# The LABEL: rule
120#
121arrow right $r from X0 then down 1.25*$r then right $r
122oval " LABEL " fit
123arrow 50%
124oval "\":\"" fit
125arrow 200%
126box "position" italic fit
127arrow
128line right until even with X9 - ($r,0) \
129  then up until even with X9 then to X9
130arrow from last oval.e right $r*0.5 then up $r*0.8 right $r*0.8
131line up $r*0.45 right $r*0.45 then right
132
133# The VARIABLE = rule
134#
135arrow right $r from X0 then down 2.5*$r then right $r
136oval " VARIABLE " fit
137arrow 70%
138box "assignment-operator" italic fit
139arrow 70%
140box "expr" italic fit
141line right until even with X9 - ($r,0) \
142  then up until even with X9 then to X9
143
144# The PRINT rule
145#
146arrow right $r from X0 then down 3.75*$r then right $r
147oval "\"print\"" fit
148arrow
149box "print-args" italic fit
150line right until even with X9 - ($r,0) \
151  then up until even with X9 then to X9
152~~~
153
154## Swimlanes
155
156From the [Branching, Forking, Merging, and Tagging][bfmt] paper on
157the Fossil website.
158
159[bfmt]: https://fossil-scm.org/fossil/doc/trunk/www/branching.wiki
160
161~~~ pikchr toggle
162    $laneh = 0.75
163
164    # Draw the lanes
165    down
166    box width 3.5in height $laneh fill 0xacc9e3
167    box same fill 0xc5d8ef
168    box same as first box
169    box same as 2nd box
170    line from 1st box.sw+(0.2,0) up until even with 1st box.n \
171      "Alan" above aligned
172    line from 2nd box.sw+(0.2,0) up until even with 2nd box.n \
173      "Betty" above aligned
174    line from 3rd box.sw+(0.2,0) up until even with 3rd box.n \
175      "Charlie" above aligned
176    line from 4th box.sw+(0.2,0) up until even with 4th box.n \
177       "Darlene" above aligned
178
179    # fill in content for the Alice lane
180    right
181A1: circle rad 0.1in at end of first line + (0.2,-0.2) \
182       fill white thickness 1.5px "1"
183    arrow right 50%
184    circle same "2"
185    arrow right until even with first box.e - (0.65,0.0)
186    ellipse "future" fit fill white height 0.2 width 0.5 thickness 1.5px
187A3: circle same at A1+(0.8,-0.3) "3" fill 0xc0c0c0
188    arrow from A1 to last circle chop "fork!" below aligned
189
190    # content for the Betty lane
191B1: circle same as A1 at A1-(0,$laneh) "1"
192    arrow right 50%
193    circle same "2"
194    arrow right until even with first ellipse.w
195    ellipse same "future"
196B3: circle same at A3-(0,$laneh) "3"
197    arrow right 50%
198    circle same as A3 "4"
199    arrow from B1 to 2nd last circle chop
200
201    # content for the Charlie lane
202C1: circle same as A1 at B1-(0,$laneh) "1"
203    arrow 50%
204    circle same "2"
205    arrow right 0.8in "goes" "offline"
206C5: circle same as A3 "5"
207    arrow right until even with first ellipse.w \
208      "back online" above "pushes 5" below "pulls 3 &amp; 4" below
209    ellipse same "future"
210
211    # content for the Darlene lane
212D1: circle same as A1 at C1-(0,$laneh) "1"
213    arrow 50%
214    circle same "2"
215    arrow right until even with C5.w
216    circle same "5"
217    arrow 50%
218    circle same as A3 "6"
219    arrow right until even with first ellipse.w
220    ellipse same "future"
221D3: circle same as B3 at B3-(0,2*$laneh) "3"
222    arrow 50%
223    circle same "4"
224    arrow from D1 to D3 chop
225~~~
226
227
228## Graphs
229
230Version control graph adapted from [Rebase Considered Harmful][rch].
231Commentary on the Pikchr source text to the first of these two
232graphs is provided in a [separate tutorial](./teardown01.md).
233
234[rch]: https://fossil-scm.org/fossil/doc/trunk/www/rebaseharm.md
235
236~~~ pikchr toggle
237scale = 0.8
238fill = white
239linewid *= 0.5
240circle "C0" fit
241circlerad = previous.radius
242arrow
243circle "C1"
244arrow
245circle "C2"
246arrow
247circle "C4"
248arrow
249circle "C6"
250circle "C3" at dist(C2,C4) heading 30 from C2
251arrow
252circle "C5"
253arrow from C2 to C3 chop
254C3P: circle "C3'" at dist(C4,C6) heading 30 from C6
255arrow right from C3P.e
256C5P: circle "C5'"
257arrow from C6 to C3P chop
258
259box height C3.y-C2.y \
260    width (C5P.e.x-C0.w.x)+linewid \
261    with .w at 0.5*linewid west of C0.w \
262    behind C0 \
263    fill 0xc6e2ff thin color gray
264box same width previous.e.x - C2.w.x \
265    with .se at previous.ne \
266    fill 0x9accfc
267"trunk" below at 2nd last box.s
268"feature branch" above at last box.n
269
270circle "C0" at 3.7cm south of C0
271arrow
272circle "C1"
273arrow
274circle "C2"
275arrow
276circle "C4"
277arrow
278circle "C6"
279circle "C3" at dist(C2,C4) heading 30 from C2
280arrow
281circle "C5"
282arrow
283circle "C7"
284arrow from C2 to C3 chop
285arrow from C6 to C7 chop
286
287box height C3.y-C2.y \
288    width (C7.e.x-C0.w.x)+1.5*C1.radius \
289    with .w at 0.5*linewid west of C0.w \
290    behind C0 \
291    fill 0xc6e2ff thin color gray
292box same width previous.e.x - C2.w.x \
293    with .se at previous.ne \
294    fill 0x9accfc
295"trunk" below at 2nd last box.s
296"feature branch" above at last box.n
297~~~
298
299## Impossible Trident
300
301Contributed by Kees Nuyt
302
303~~~ pikchr toggle
304# Impossible trident pikchr script
305# https://en.wikipedia.org/wiki/Impossible_trident
306# pikchr script by Kees Nuyt, license Creative Commons BY-NC-SA
307# https://creativecommons.org/licenses/by-nc-sa/4.0/
308
309scale = 1.0
310eh = 0.5cm
311ew = 0.2cm
312ed = 2 * eh
313er = 0.4cm
314lws = 4.0cm
315lwm = lws + er
316lwl = lwm + er
317
318ellipse height eh width ew
319L1: line width lwl from last ellipse.n
320line width lwm from last ellipse.s
321LV: line height eh down
322
323move right er down ed from last ellipse.n
324ellipse height eh width ew
325L3: line width lws right from last ellipse.n to LV.end then down eh right ew
326line width lwm right from last ellipse.s then to LV.start
327
328move right er down ed from last ellipse.n
329ellipse height eh width ew
330line width lwl right from last ellipse.n then to L1.end
331line width lwl right from last ellipse.s then up eh
332~~~
333
334
335## PIC Examples From The [Brian W. Kernighan paper][bwk]
336
337[bwk]: /uv/pic.pdf
338
339-----
340
341From page 18.
342
343~~~ pikchr toggle
344define ndblock {
345  box wid boxwid/2 ht boxht/2
346  down;  box same with .t at bottom of last box;   box same
347}
348boxht = .2; boxwid = .3; circlerad = .3; dx = 0.05
349down; box; box; box; box ht 3*boxht "." "." "."
350L: box; box; box invis wid 2*boxwid "hashtab:" with .e at 1st box .w
351right
352Start: box wid .5 with .sw at 1st box.ne + (.4,.2) "..."
353N1: box wid .2 "n1";  D1: box wid .3 "d1"
354N3: box wid .4 "n3";  D3: box wid .3 "d3"
355box wid .4 "..."
356N2: box wid .5 "n2";  D2: box wid .2 "d2"
357arrow right from 2nd box
358ndblock
359spline -> right .2 from 3rd last box then to N1.sw + (dx,0)
360spline -> right .3 from 2nd last box then to D1.sw + (dx,0)
361arrow right from last box
362ndblock
363spline -> right .2 from 3rd last box to N2.sw-(dx,.2) to N2.sw+(dx,0)
364spline -> right .3 from 2nd last box to D2.sw-(dx,.2) to D2.sw+(dx,0)
365arrow right 2*linewid from L
366ndblock
367spline -> right .2 from 3rd last box to N3.sw + (dx,0)
368spline -> right .3 from 2nd last box to D3.sw + (dx,0)
369circlerad = .3
370circle invis "ndblock"  at last box.e + (1.2,.2)
371arrow dashed from last circle.w to 5/8<last circle.w,2nd last box> chop
372box invis wid 2*boxwid "ndtable:" with .e at Start.w
373~~~
374
375
376-----
377
378From page 19:  The "intermediate code" line had to
379be lengthened so that the text would fit.
380
381~~~ pikchr toggle
382        arrow "source" "code"
383LA:     box "lexical" "analyzer"
384        arrow "tokens" above
385P:      box "parser"
386        arrow "intermediate" "code" wid 200%
387Sem:    box "semantic" "checker"
388        arrow
389        arrow <-> up from top of LA
390LC:     box "lexical" "corrector"
391        arrow <-> up from top of P
392Syn:    box "syntactic" "corrector"
393        arrow up
394DMP:    box "diagnostic" "message" "printer"
395        arrow <-> right  from east of DMP
396ST:     box "symbol" "table"
397        arrow from LC.ne to DMP.sw
398        arrow from Sem.nw to DMP.se
399        arrow <-> from Sem.top to ST.bot
400~~~
401
402------
403
404From page 20:  Various minor tweaks
405
406~~~ pikchr toggle
407        circle "DISK"
408        arrow "character" "defns" right 150%
409CPU:    box "CPU" "(16-bit mini)"
410        arrow <- from top of CPU up "input " rjust
411        move right from CPU.e
412CRT:    "   CRT" ljust
413        line from CRT - 0,0.075 up 0.15 \
414                then right 0.5 \
415                then right 0.5 up 0.25 \
416                then down 0.5+0.15 \
417                then left 0.5 up 0.25 \
418                then left 0.5
419        arrow from CPU.e right until even with previous.start
420Paper:  CRT + 1.05,0.75
421        arrow <- from Paper down 1.5
422        " ...  paper" ljust at end of last arrow + 0, 0.25
423        circle rad 0.05 at Paper + (-0.055, -0.25)
424        circle rad 0.05 at Paper + (0.055, -0.25)
425        "   rollers" ljust at Paper + (0.1, -0.25)
426~~~
427