doc/parts/tutorial/chap-hello.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-hello">
  19 <title>Hello, Shaper!</title>
  20 <top>
  21 <p>Let's begin by working through a very small example.  We'll just make a diagonal line — that's pretty much the simplest thing I can think of.  (Making a very small spot would actually be simpler, but creating lines is such an important topic for <str-Shapes /> that it ought to be part of the first example.)</p>
  22 </top>
  23
  24 <section id="hello/state-free">
  25 <title>The really short source</title>
  26 <body>
  27         <p>
  28                 A <str-Shapes /> program may consist of just one expression.  For this example,
  29 <pre>
  30 [stroke (0cm,0cm)--(2cm,1cm)]
  31 </pre>
  32 would be a valid program.  However, to display one of the fundamental language constructs of <str-Shapes />, we shall look at a slightly more clumsy way of achieving the same result.
  33         </p>
  34         <p>Please refer to <a part="structure" /> for an explanation of the various ways a <str-Shapes /> program may define its output.</p>
  35 </body>
  36 </section><!-- End of hello/state-free -->
  37
  38 <section id="hello/source">
  39 <title>The source</title>
  40 <body>
  41         <p>
  42                 The following, slightly longer, program does the same job as the program in the previous section.  It's still just one line of code, and it will be explained in just a moment:
  43 <pre>
  44 &bullet;page &lt;&lt; [stroke (0cm,0cm)--(2cm,1cm)]
  45 </pre>
  46         </p>
  47
  48         <p>
  49                 If you don't like the bullet character (&bullet;), you may prefix <inline>page</inline> with a hash sign (#) instead, like so:
  50 <pre>
  51 #page &lt;&lt; [stroke (0cm,0cm)--(2cm,1cm)]
  52 </pre>
  53         </p>
  54
  55         <p>In either case, make sure your file is encoded using <str-UTF-8 /> (if you avoid the bullet character, most eight bit encodings should be fine by intended coincidence).  Call the file <filename>hello.shape</filename>.</p>
  56
  57         <p>So what does the code mean?  As you namespace="..Shapes..IO" might have guessed, <state name="page" />, has something to do with the <quote>page</quote> we are drawing on, and the following <inline>&lt;&lt;</inline> is an insertion operator (borrowed from <str-C-plus-plus />) that takes the following argument and <em>tacks it onto</em> the page.  The expression delimited by square brackets is a <em>function call</em>; here <value namespace="..Shapes..Graphics" name="stroke" /> is the callee, and there is one argument.  The argument is a straight path between two points, simply constructed by combining the two coordinate pairs using the <em>connection operator</em> <operator name="--" />.</p>
  58
  59         <p>
  60                 The example displays the following traits of the <str-Shapes /> language
  61                 <ol>
  62                         <li><p>Function calls have the callee <em>inside</em> the bracketing syntax, like in Scheme.</p></li>
  63                         <li><p>Statements are not terminated using a designated token; statements end by themselves, like in Haskell.</p></li>
  64                         <li><p><em>States</em> (here, <state namespace="..Shapes..IO" name="page" />) and <em>variables</em> (here, <value namespace="..Shapes..Graphics" name="stroke" />) are distinguished by belonging to different name spaces, like variables are distinguished from types in Haskell.  This is called <em>Hungarian notation</em>, and is used also for other distinctions in <str-Shapes />.</p></li>
  65                         <li><p>Coordinates are specified as pairs of lengths, as opposed to pairs of scalars, unlike many other graphics languages where there is no distinction between lengths and scalars.</p></li>
  66                         <li><p>The syntax makes use of characters outside the ASCII range, but there is always ASCII fall-backs.</p></li>
  67                 </ol>
  68         </p>
  69 </body>
  70 </section><!-- End of hello/source -->
  71
  72 <section id="hello/compile">
  73 <title>Compiling and viewing</title>
  74 <body>
  75 <p>
  76         To obtain the pretty piece of graphics so carefully designed above, we just need to pass the file to the <str-Shapes /> compiler:
  77 <command-line>
  78 shapes hello.shape
  79 </command-line>
  80 </p>
  81
  82 <p>
  83         This will produce the file <filename>hello.pdf</filename>, and if your favorite <str-PDF /> viewer happens to be xpdf, you could open the file by typing
  84 <command-line>
  85 xpdf hello.pdf &amp;
  86 </command-line>
  87 </p>
  88
  89 <p>
  90         However, when your file changes, you will want to update the xpdf window, and then <str-Shapes /> comes to the rescue; try using the compiler with an extra option:
  91 <command-line>
  92 shapes --xpdf hello.shape
  93 </command-line>
  94 </p>
  95
  96 <p>If you're on a Mac, you may replace <inline>--xpdf</inline> by <inline>--open</inline>.</p>
  97
  98 </body>
  99 </section><!-- End of hello/compile -->
 100
 101 <section id="hello/final-comments">
 102 <title>Final comments</title>
 103 <body>
 104 <p>If you reached this point, this shows you're up and running!  You're ready to go on with more exciting examples!  By the way, can you figure out how you would go about to add another stroke to your page, or a longer stroke connecting several points?</p>
 105 <p>There are many things the user can control using command line options to the compiler, but these won't be covered in this tutorial.  Please refer to the <a part="man">man page</a> for further details on this.</p>
 106 </body>
 107 </section><!-- End of hello/final-comments -->
 108
 109 </section><!-- end of chap-hello -->