doc/parts/structure/chap-result.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, 2015 Henrik Tidefelt                                   -->
  17
  18 <section id="chap-result">
  19 <title>Program result</title>
  20 <top>
  21         <p>The <str-Shapes /> compiler will run either in <a part="man" id="mode">shape mode</a> or in <a part="man" id="mode">blank mode</a>, typically determined by the suffix of the input filename.</p>
  22 </top>
  23
  24 <section id="chap-result/shape">
  25 <title>Shape mode</title>
  26 <body>
  27         <p><a part="man" id="mode">Shape mode</a> is selected for input files with suffix <filename>.shapes</filename>, or when in doubt.</p>
  28         <p>In shape mode, the only necessary aspect to discuss regarding the global structure of a <str-Shapes /> program is how the graphical output is defined.  There are three means for defining the output of a <str-Shapes /> program:
  29                 <ul>
  30                         <li>Through the value of the program as an expression.  If the program results in a non-<named-type name="Void" /> value, it must be a <named-type name="Drawable" />, and not a null-picture.  The result will be a single-page document.</li>
  31                         <li>Through a non-empty final value of <state namespace="..Shapes..IO" name="page" />.  For single-page documents.  This is equivalent to ending the program with the expression <inline>(<state namespace="..Shapes..IO" name="page" />)</inline>.</li>
  32                         <li>Through a non-empty final value of <state namespace="..Shapes..IO" name="catalog" />.  For multi-page documents.</li>
  33                 </ul>
  34         </p>
  35         <p>At least one of the alternatives must be used by the program.  It is, however, not necessary that exactly on is used; some combinations are OK due to precedence rules.</p>
  36         <p>It is illegal to both add pages to <state namespace="..Shapes..IO" name="catalog" /> and let the program evaluate to a value.  The other combinations are allowed by giving precedence to <state namespace="..Shapes..IO" name="catalog" /> and program value over <state namespace="..Shapes..IO" name="page" />.  Hence, <state namespace="..Shapes..IO" name="page" /> is only used when it is the only alternative in use.</p>
  37         <p>The rationale behind the precedence rule is that <state namespace="..Shapes..IO" name="page" /> may be used to define pages of multi-page documents, and then the rule relieves us from having to clear <state namespace="..Shapes..IO" name="page" /> at the end of the program.  Similarly, if one finds that the final content of <state namespace="..Shapes..IO" name="page" /> needs to be transformed for some reason, one may apply the transform to <inline>(<state namespace="..Shapes..IO" name="page" />)</inline> at the end of the program, without having to clear <state namespace="..Shapes..IO" name="page" />.</p>
  38 </body>
  39 </section><!-- end of chap-result/shape -->
  40
  41 <section id="chap-result/blank">
  42 <title>Blank mode</title>
  43 <body>
  44         <p><a part="man" id="mode">Blank mode</a> is selected for input files with suffix <filename>.blank</filename>.</p>
  45         <p>In blank mode, the <str-Shapes /> compiler is not expecting a graphical result to be defined, and will not write any results to output files.  In this mode, the program result is not in any standardized format.  One common case is a program which just produces output on <filename>stdout</filename>.</p>
  46 </body>
  47 </section><!-- end of chap-result/blank -->
  48
  49 </section><!-- end of chap-result -->