Overview
Comment: | Fixed assorted typos, clarity errors, and formatting problems in the docs. Most were reported on the forum by brickviking (here and here) but I found and fixed a few more while in there. |
---|---|
Downloads: | Tarball | ZIP archive | SQL archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA3-256: |
8c0dfc54311962c1cccab4a05a3f60c6 |
User & Date: | wyoung 2023-05-26 09:26:17 |
Original Comment: | Fixed assorted typos, clarity errors, and formatting problems in the docs. Most were reported on the forum by brickviking (/forumpost/67377861d9 | here] and here) but I found and fixed a few more while in there. |
References
2023-05-26
| ||
09:28 | • Reply: Some more small corrections (artifact: 11fa8520f1 user: wyoung) | |
09:27 | • Reply: typo (artifact: dfea06b958 user: wyoung) | |
Context
2023-05-26
| ||
11:37 | Typo fix, reported on the forum. (check-in: 6d40a5f041 user: wyoung tags: trunk) | |
09:26 | Fixed assorted typos, clarity errors, and formatting problems in the docs. Most were reported on the forum by brickviking (here and here) but I found and fixed a few more while in there. (check-in: 8c0dfc5431 user: wyoung tags: trunk) | |
2023-05-18
| ||
16:57 | Remove the artificial enlargement of "mono" text, as that seems not to be necessary when the output is rendered by Fossil. Must be some kind of CSS issue. (check-in: 03664a38cf user: drh tags: trunk) | |
Changes
Changes to doc/circleobj.md.
1 2 | # Circle objects | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | # 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) |
︙ | ︙ |
Changes to doc/differences.md.
︙ | ︙ | |||
423 424 425 426 427 428 429 | 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. | | | 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 | 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 |
︙ | ︙ |
Changes to doc/download.md.
︙ | ︙ | |||
27 28 29 30 31 32 33 | * <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. | | | 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | * <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 |
︙ | ︙ | |||
54 55 56 57 58 59 60 | * `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 | | | < | | 54 55 56 57 58 59 60 61 62 63 64 | * `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). |
Changes to doc/ellipseobj.md.
|
| | | | < | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | # 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 ~~~~ |
Changes to doc/fileobj.md.
1 2 3 4 5 6 | # 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 | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 | # 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>) |
︙ | ︙ |
Changes to doc/linelen.md.
1 2 3 4 5 6 7 8 9 10 11 12 | # 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 | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | # 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. |
Changes to doc/pathattr.md.
1 2 | # path-attribute | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 | # 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* |
︙ | ︙ | |||
85 86 87 88 89 90 91 | "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 | | | 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | "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. |
︙ | ︙ |
Changes to doc/stmt.md.
︙ | ︙ | |||
105 106 107 108 109 110 111 | | 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 | | | | 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 | | 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. |
︙ | ︙ |
Changes to doc/stmtlist.md.
︙ | ︙ | |||
61 62 63 64 65 66 67 | 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 | | | 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 | 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 |
︙ | ︙ |
Changes to doc/teardown01.md.
︙ | ︙ | |||
78 79 80 81 82 83 84 | 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 | | | 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | 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 |
︙ | ︙ | |||
165 166 167 168 169 170 171 | 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. | | | 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 | 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. |
︙ | ︙ | |||
204 205 206 207 208 209 210 | 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. | | | 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | 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. |
︙ | ︙ | |||
253 254 255 256 257 258 259 | 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. | | | 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 | 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 |
︙ | ︙ |
Changes to doc/userman.md.
︙ | ︙ | |||
10 11 12 13 14 15 16 | 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 | | | 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | 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> |
︙ | ︙ | |||
45 46 47 48 49 50 51 | 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 | | | | | 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 | 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 |
︙ | ︙ | |||
421 422 423 424 425 426 427 | 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 | | | | 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 | 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 |
︙ | ︙ | |||
1189 1190 1191 1192 1193 1194 1195 | 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> | | | | | > | 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 | 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% ~~~~ |
︙ | ︙ |