doc/parts/tutorial/chap-basics.sxml

   1 <!-- This file is part of Shapes.                                           -->
   2 <!--                                                                        -->
   3 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   4 <!-- it under the terms of the GNU General Public License as published by   -->
   5 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   6 <!-- any later version.                                                     -->
   7 <!--                                                                        -->
   8 <!-- Shapes is distributed in the hope that it will be useful,              -->
   9 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  10 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  11 <!-- GNU General Public License for more details.                           -->
  12 <!--                                                                        -->
  13 <!-- You should have received a copy of the GNU General Public License      -->
  14 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  15 <!--                                                                        -->
  16 <!-- Copyright 2008 Henrik Tidefelt                                         -->
  17
  18 <section id="chap-basics">
  19 <title>Basics</title>
  20 <top>
  21 <p>In this chapter, we'll quickly go through a couple of simple but important things about the <str-Shapes /> language.</p>
  22 </top>
  23
  24 <section id="basics/LaTeX">
  25 <title>Producing nice labels with LaTeX</title>
  26 <body>
  27 <p>
  28         The following example shows how to produce a label typeset using <str-LaTeX />:
  29 <pre>
  30 &bullet;page &lt;&lt; (TeX <char-str-open />$\Xi^{2}$<char-str-close />)
  31 </pre>
  32 </p>
  33
  34 <p>
  35         Things worth noting:
  36         <ol>
  37                 <li><p>There is no function call here.  The expression delimited by parentheses is a special form indicated by the <operator name="TeX" /> keyword.</p></li>
  38                 <li><p>The string delimiters is a pair of one grave and once acute accent.  If you find these difficult to produce using your keyboard layout, there is an alternative syntax; the poor man's string combines straight double quote marks with a pair of parentheses, in this case <inline>("$\Xi^{2}$")</inline>.</p></li>
  39                 <li><p>The backslash character (\) is not an escape character (there is no escape character at all in normal strings).</p></li>
  40                 <li><p><str-LaTeX /> is also useful for including pictures via the <inline>includegraphics</inline> macro.</p></li>
  41         </ol>
  42 </p>
  43
  44 <note>
  45         <p>The <syntax name="string" /> syntax is chosen carefully not to interfere with the use of <str-LaTeX /> — that's why there is no escape character.</p>
  46 </note>
  47
  48 <note>
  49 <p>There is also a function that does the same job as the <operator name="TeX" /> special form, but there are good reasons for avoiding it.</p>
  50 </note>
  51
  52 <example-with-output title="Quotation marks in labels" internal-id="example:tex-quotes">
  53 <image pdf="doc/tex-quotes.pdf" jpg="doc/tex-quotes_y_big.jpg" />
  54 <source file="doc/tex-quotes.shape">
  55 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/tex-quotes.shape" -->]]>
  56 </source>
  57 <caption>
  58         <p>Since <str-Shapes /> allows pairwise `…´ inside normal strings, the ` cannot be used to create the left double quote in <str-LaTeX />, since there will be no matching ´ at the other end of the quote.  This example presents ways to deal with this.</p>
  59 </caption>
  60 </example-with-output>
  61
  62 </body>
  63 </section><!-- End of basics/LaTeX -->
  64
  65 <section id="basics/transforms">
  66 <title>Moving things around</title>
  67 <body>
  68 <p>When putting strokes on the page, there is a natural way of controlling where the strokes appear by simply specifying the desired coordinates.  When using the <operator name="TeX" /> special form, however, the produced graphics always ends up at the origin.  We clearly need to be able to move things around… well, strictly speaking, we don't <em>move</em> things in <str-Shapes />, since the language is functional.  What we really do is create a new object which only differs from the original by a <em>transform</em>, see <named-type name="Transform" />.</p>
  69 <p>
  70         In <str-Shapes /> each transform is represented as an object in itself, which can then be applied to objects of geometric nature.  For example, to create the transform that moves (<em>shifts</em>, see <value namespace="..Shapes..Geometry" name="shift" />) things <physical><scalar>2</scalar><unit>cm</unit></physical> to the right and <physical><scalar>3</scalar><unit>mm</unit></physical> down, we write (we also give a name to the transform, so that it can be referred to later):
  71 <pre>
  72 T1: [shift (2cm,~3mm)]
  73 </pre>
  74 </p>
  75 <p>
  76         Note:
  77         <ol>
  78                 <li><p>The sign of a negative number or length is written using the tilde (~) character.  Negative values can also be written using the usual dash (-) if enclosed withing parentheses, for instance, <inline>(2cm,(-3mm))</inline>.  The latter alternative is convenient when the source is produced by other programs.</p></li>
  79         </ol>
  80 </p>
  81
  82 <p>Another very common transformation is rotation (see <value namespace="..Shapes..Geometry" name="rotate" />):
  83 <pre>
  84 T2: [rotate 25°]
  85 </pre>
  86 </p>
  87 <p>
  88         Note:
  89         <ol>
  90                 <li><p>The angle argument is basically interpreted as radians, but angles may be entered in degrees if immediately followed by the degree sign (°).  In fact, <inline>25°</inline> is just a way of entering the number 25⋅π/180.  For the full syntax of floats and a note on how to type the degree sign, see <syntax name="float" />.</p></li>
  91         </ol>
  92 </p>
  93 <p>
  94         The following program illustrates how the transforms can be applied:
  95 <pre>
  96 lbl: (TeX `$x^{2} + y^{2}$´)
  97 &bullet;page &lt;&lt; [T1 lbl] &lt;&lt; [T2 lbl] &lt;&lt; lbl
  98 </pre>
  99 </p>
 100
 101 <p>The complete example with output is given below.</p>
 102 <example-with-output title="Transforms" internal-id="example:transforms">
 103 <image pdf="doc/tutorial-transforms_3.pdf" jpg="doc/tutorial-transforms_y_big.jpg" />
 104 <source file="doc/tutorial-transforms.shape">
 105 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/tutorial-transforms.shape" -->]]>
 106 </source>
 107 <caption>
 108         <p>A label painted once in its original location, once after a rotation, and once after a shift.</p>
 109 </caption>
 110 </example-with-output>
 111
 112 <p>
 113         Transforms can be combined using the multiplication operator (<operator name="*" />).  Hence, the following two lines do the same thing:
 114 <pre>
 115 &bullet;page &lt;&lt; [T2 [T1 lbl]]
 116 &bullet;page &lt;&lt; [T2*T1 lbl]
 117 </pre>
 118 </p>
 119 <p>It is almost allways the case that combining the operators is (sometimes much) more efficient than applying one transform after the other.</p>
 120
 121 <p>Well, that's about all we are going to say regarding transforms in this tutorial.  Before ending, we'll just mention that there are other constructors beside the ones seen here, that (almost all) transforms can be inverted (see <value namespace="..Shapes..Geometry" name="inverse" />), and that transforms also exist in <str-3D /> (see <named-type name="Transform3D" />).</p>
 122 </body>
 123 </section><!-- End of basics/transforms -->
 124
 125 <section id="basics/paths">
 126 <title>Constructing paths</title>
 127 <body>
 128 <p>Path construction is at the heart of the <str-Shapes /> language, and we shall cover only a small part of the powerful ways in which paths can be specified.  The main documentation on path construction is in the <a part="syntax" id="syntax/misc-expr/path-constr">syntax chapter</a>.</p>
 129
 130 <p>Basically, path construction is about entering coordinates in a convenient way.  The cubic splines (often referred to as <em>Bezier splines</em>) that <str-Shapes /> uses for paths (which is the obvious choice since this is was is supported by <str-PDF />) consist both of points <em>on</em> the path and interpolation points that control the shape of the path between the points that are on the path.  Basically each path segment between two points on the path have one interpolation point associated with the starting point, and one associated with the final point.  Each of the interpolation points may be omitted, which corresponds to the limiting case when the interpolation point approaches the associated point on the path.  The following example tries to illustrate the roles of points on the path and of the interpolation points.</p>
 131 <example-with-output title="Single Bezier spline" internal-id="example:one-segment">
 132 <image pdf="doc/tutorial-one-segment_3.pdf" jpg="doc/tutorial-one-segment_y_big.jpg" />
 133 <source file="doc/tutorial-one-segment.shape">
 134 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/tutorial-one-segment.shape" -->]]>
 135 </source>
 136 <caption>
 137         <p>Bezier splines.  Points on the path are marked with circles, and interpolation points are marked with a cross and a dashed line showing which terminal point it belongs to.  Absence of an interpolation point — that is, an interpolation point which is logically coinciding with the terminal point it is associated with — is simply represented by not marking the interpolation point at all.  Note that the absence of an interpolation point is the limiting case as the interpolation point approaches the terminal point.</p>
 138 </caption>
 139 </example-with-output>
 140
 141 <p>In the next example we will see how to connect spline segments, and how offsets are interpreted.</p>
 142
 143 <example-with-output title="Connected Bezier splines" internal-id="example:bezier-connected">
 144 <image pdf="doc/tutorial-bezier-connected_3.pdf" jpg="doc/tutorial-bezier-connected_y_big.jpg" />
 145 <source file="doc/tutorial-bezier-connected.shape">
 146 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/tutorial-bezier-connected.shape" -->]]>
 147 </source>
 148 <caption>
 149         <p>Bezier splines.  Points on the path are marked with circles, and interpolation points are marked with a cross and a dashed line showing which terminal point it belongs to.  Solid lines with arrowhead indicates how offset coordinates are interpreted during path construction.</p>
 150 </caption>
 151 </example-with-output>
 152
 153 <p>
 154         Given the examples above, the following observations and claims regarding path construction should seem at least plausible:
 155         <ol>
 156                 <li><p>When the path leaves a through-point, it does so in direction towards the next interpolation point, or the next through-point if there are no interpolation points.</p></li>
 157                 <li><p>Hence, to avoid a corner at a path point, its handles mush point in opposite directions.</p></li>
 158                 <li><p>To avoid discontinuity in the second order derivatives, the handles shall additionally be of equal lengths.</p></li>
 159                 <li><p>Since angles to interpolation points are so important, it is desirable to be able to enter interpolation points in polar coordinates, relative to the through-point.</p></li>
 160                 <li><p>Specifying the distance to the interpolation points is not as intuitive as specifying the angles.</p></li>
 161                 <li><p>Hence, some mechanism for automatic determination of such distances should be welcome.</p></li>
 162                 <li><p>A mechanism for automatic determination of angles should be welcome too.</p></li>
 163                 <li><p>Automatic choices and values set directly by the user should mix in a way that allows complete freedom to mix the two, while also being easy to learn and remember.</p></li>
 164                 <li><p>While it is possible to use polar coordinates to specify interpolation points relative to the through-point by using the <value namespace="..Shapes..Geometry" name="dir" /> function, for example <inline>(+ r*[dir a])</inline>, this solution has no room for automatic choices.</p></li>
 165         </ol>
 166         Of course, all of these features are available in <str-Shapes />.  The syntax may feel a bit clumsy initially, but that's the small price we pay for the powerful and easy to remember syntax, see <syntax name="polar-handle-2D" /> and <syntax name="corner-point-2D" />.
 167 </p>
 168
 169 <p>While automatic angles are determined using a rather simple scheme, selecting the distances is much more complicated.  In <str-Shapes />, angles are always determined before determining any distances.  This means that a scheme for automatic determination of distances has to determine these based on the location of the through-points and the angles from the through-points to the intermediate interpolation points.  (When the two distances at a path point shall be equal, and both are to be determined automatically, then both are determined individually first, and then the smaller is used on both sides of the path point.)  It is easy to see that the task is over-parameterized as stated here, and that the coordinates of the through-points can be reduced to just the distance between.  A <a part="syntax" id="syntax/atoms/special-lengths"><em>special unit</em></a> is a mapping from the three resulting parameters to a length.  The most frequently used special unit is <inline>%C</inline>, which helps to produce circular arcs.</p>
 170
 171 <p>The use of polar handle coordinates and automatic determination of angles and distances will not be discussed further in this tutorial.  The reader is encouraged to follow the links in the text to the reference documentation in order to learn more about path construction.</p>
 172
 173 </body>
 174 </section><!-- End of basics/paths -->
 175
 176 <section id="basics/path-painting">
 177 <title>Painting paths</title>
 178 <body>
 179 <p>You are already familiar with one of the path-painting functions, namely <value namespace="..Shapes..Graphics" name="stroke" />.  A similar function, <value namespace="..Shapes..Graphics" name="fill" />, will fill the path with paint instead of stroking it, and <value namespace="..Shapes..Graphics" name="fillstroke" /> will do both.  The following example also shows how to put an arrowhead on the path while stroking it.  Besides, it also shows how <value namespace="..Shapes..Graphics" name="spot" /> is used to make a round spot at a given point.</p>
 180 <example-with-output title="Path-painting" internal-id="example:path-painting">
 181 <image pdf="doc/tutorial-path-painting_3.pdf" jpg="doc/tutorial-path-painting_y_big.jpg" />
 182 <source file="doc/tutorial-path-painting.shape">
 183 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/tutorial-path-painting.shape" -->]]>
 184 </source>
 185 <caption>
 186         <p>Filling, stroking, filling-and-stroking, and stroking a path with an arrow head.  Spotting a point can be seen as a special case of stroking a singleton path.</p>
 187 </caption>
 188 </example-with-output>
 189 <p>
 190         Things to note:
 191         <ol>
 192                 <li><p>The arrowheads are defined in a <str-Shapes /> <em>extension</em> file.  If your <str-Shapes /> compiler has the path <filename>/usr/local/bin/shapes</filename>, then the extension files are typically located in <filename>/usr/local/share/shapes/extenions/</filename>.</p></li>
 193                 <li><p>Functions can take <em>named arguments</em>, and here the argument called <arg name="head" /> is some kind of object which defines what the arrowhead shall look like.</p></li>
 194                 <li><p>As you might have guessed, <value namespace="..Shapes..Graphics" name="stroke" /> also takes an argument called <arg name="tail" />.</p></li>
 195         </ol>
 196 </p>
 197 </body>
 198 </section><!-- End of basics/path-painting -->
 199
 200 <section id="basics/colors">
 201 <title>Changing graphics parameters, such as color</title>
 202 <body>
 203 <p>Until now, all our drawings have been black on white, and all strokes of the default width <physical><scalar>1</scalar><unit>bp</unit></physical>.  In <str-PDF /> such properties are part of the <em>graphics state</em>, and <str-Shapes /> gives you control over these parameters via dynamic variables (see <a id="prog/functions" /> below); just like <dynamic namespace="..Shapes..Geometry" name="defaultunit" /> has an impact on how smooth paths come out, <dynamic namespace="..Shapes..Traits" name="width" /> controls how thick the lines coming from <value namespace="..Shapes..Graphics" name="stroke" /> are.</p>
 204 <p>As usual, we use an example to show what the most important parameters are called, and how to set them.</p>
 205 <example-with-output title="Graphics-params" internal-id="example:graphics-params">
 206 <image pdf="doc/tutorial-graphics-params_3.pdf" jpg="doc/tutorial-graphics-params_y_big.jpg" />
 207 <source file="doc/tutorial-graphics-params.shape">
 208 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/tutorial-graphics-params.shape" -->]]>
 209 </source>
 210 <caption>
 211         <p>Changing parameters in the <str-PDF /> graphics state, such as stroking and non-stroking (that is, fill) color, dashpattern, <abbr-etc />.</p>
 212 </caption>
 213 </example-with-output>
 214 <p>
 215         Things to note:
 216         <ol>
 217                 <li><p>The various ways several dynamic bindings can be combined to one set of bindings, including using the function <value namespace="..Shapes" name="bindings" /> and inserting the empty set of bindings <value namespace="..Shapes" name="nullbind" /> explicitly to make it one operator <operator name="&amp;" /> per binding.</p></li>
 218         </ol>
 219 </p>
 220 </body>
 221 </section><!-- End of basics/colors -->
 222
 223 <section id="basics/final-comments">
 224 <title>Final comments</title>
 225 <body>
 226 <p>By now you know how to construct the most important basic elements that constitute the visual contents of a page.  Thus you are ready to use <str-Shapes /> as a meta-language for <str-PDF /> — indeed, the first name of the language was <em>MetaPDF</em> — but that is not what <str-Shapes /> is meant for.  <str-Shapes /> is all about <em>how</em> you put these elements on the page, and to this end you need to learn more about what programming in <str-Shapes /> is like.</p>
 227 </body>
 228 </section><!-- End of basics/final-comments -->
 229
 230 </section><!-- End of chap-basics -->