doc/parts/man/index.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2
   3 <!-- This file is part of Shapes.                                           -->
   4 <!--                                                                        -->
   5 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   6 <!-- it under the terms of the GNU General Public License as published by   -->
   7 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   8 <!-- any later version.                                                     -->
   9 <!--                                                                        -->
  10 <!-- Shapes is distributed in the hope that it will be useful,              -->
  11 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  12 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  13 <!-- GNU General Public License for more details.                           -->
  14 <!--                                                                        -->
  15 <!-- You should have received a copy of the GNU General Public License      -->
  16 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  17 <!--                                                                        -->
  18 <!-- Copyright 2008, 2010 Henrik Tidefelt                                   -->
  19
  20 <!DOCTYPE man [
  21 <!ENTITY bullet "<char-bullet />">
  22 <!ENTITY str-open "<char-str-open />">
  23 <!ENTITY str-close "<char-str-close />">
  24 ]>
  25 <man>
  26         <manhead prog-name="shapes"
  27                                          section="1"
  28                                          modification-date=<!--#expand-next-string-->"$(MODIFICATION_DATE)">
  29                 <left-footer>Tiddes</left-footer>
  30                 <center-header>The <str-Shapes /> language compiler</center-header>
  31                 <description>
  32                         <p>Man page descripting the commad line interface of the compiler.</p>
  33                 </description>
  34                 <meta-selflink><part-href name="man" /></meta-selflink>
  35                 <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  36                 <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  37                 <html-doc-index href=<!--#expand-next-string-->"$(HTML_DOC_DIR)/index.html" />
  38         </manhead>
  39
  40         <section>
  41                 <title>Name</title>
  42                 <body>
  43                         <p>shapes — Compile a <str-Shapes /> source to <str-PDF />.</p>
  44                 </body>
  45         </section>
  46
  47         <section>
  48                 <title>Synopsis</title>
  49                 <body>
  50                         <synopsis-table>
  51                                 <synopsis-case><prog-name>shapes</prog-name> <synatxname>option</synatxname><bnf>*</bnf> <replacable>source</replacable></synopsis-case>
  52                                 <synopsis-case><prog-name>shapes</prog-name> <synatxname>option</synatxname><bnf>*</bnf></synopsis-case>
  53                                 <synopsis-case><prog-name>shapes</prog-name> <bnf>(</bnf> <synatxname>options</synatxname> <bnf>|</bnf> <synatxname>file-request</synatxname> <bnf>)*</bnf></synopsis-case>
  54                                 <synopsis-case><prog-name>shapes</prog-name> --help</synopsis-case>
  55                         </synopsis-table>
  56                 </body>
  57         </section>
  58
  59         <section id="description">
  60                 <title>Description</title>
  61                 <body>
  62                         <p><prog-name>shapes</prog-name> compiles a source file written in the <str-Shapes /> language, with filename suffix <filename>.shape</filename> (<em>shape mode</em>) or <filename>.blank</filename> (<em>blank mode</em>).  On success and unless in blank mode, this results in a <str-PDF /> file (or a directory of files) containing a viewable representation of the graphics described by the source.</p>
  63                 </body>
  64         </section>
  65
  66         <section>
  67                 <title>Command line options</title>
  68                 <top>
  69                         <p>Command line options fall into two cathegories, most of which were referred to as <synatxname>option</synatxname> above.  The others, found in the last subsection below, are used to request which files would be used under given circumstances, and will cause the compiler to terminate without processing any files, these options were referred to as <synatxname>file-request</synatxname> above.</p>
  70                         <p>Options for setting or clearing flags are written as one entity, ending with <em>=bool</em>, where <em>bool</em> can be any of: <em>yes</em>, <em>true</em>, <em>on</em>, <em>no</em>, <em>false</em>, <em>off</em>.</p>
  71                 </top>
  72                 <section>
  73                         <title>Files</title>
  74                         <body>
  75                                 <command-line-option-list>
  76                                         <command-line-item>
  77                                                 <parameters flag="source"></parameters>
  78                                                 <description>
  79                                                         <p>When the source is specified as the last command line argument, it may have either of the forms <filename>indir/basename</filename>, <filename>indir/basename.</filename>, or <filename>indir/basename.shape</filename> (or <filename>indir/basename.blank</filename> for blank mode); they all mean the same (here <filename>indir/</filename> just indicates that the file may be located in another directory).  This also specifies a filename base (excluding <filename>indir/</filename> and the <filename>.shape</filename> or <filename>.blank</filename> suffix), which in turn provides names for all other files involved.</p>
  80                                                 </description>
  81                                         </command-line-item>
  82                                         <command-line-item>
  83                                                 <parameters flag="--outdir"> <replacable>dir</replacable></parameters>
  84                                                 <description>
  85                                                         <p>Specify directory for products.  Defaults to current working directory.  Not used in blank mode.</p>
  86                                                 </description>
  87                                         </command-line-item>
  88                                         <command-line-item>
  89                                                 <nosep-parameter flag="--split=">no/flat/dir</nosep-parameter>
  90                                                 <description>
  91                                                         <p>Determines how to store the pages of the produced document catalog.</p>
  92                                                         <p>When <em>no</em>:  One file with many pages is created.</p>
  93                                                         <p>When <em>flat</em>:  One output file per page in the catalog is created.  The file names are deduced from the output file name (see --out) which should not have any suffix, by adding the suffix <filename>-n.pdf</filename>, where <em>n</em> is the physical page number.  <em>All files that have names similar to the ones created will be deleted to avoid confusion!</em></p>
  94                                                         <p>When <em>dir</em>:  The output filename will denote a directory where each page in the catalog is stored as a separate file.  The name of each file will be <filename>n.pdf</filename> where <em>n</em> is the physical page number.  <em>All files that have names similar to the ones created will be deleted to avoid confusion!</em>  It is an error if the output filename references an existing file.</p>
  95                                                         <p>Defaults to <em>no</em>.</p>
  96                                                         <p>Splitting and file naming based on page labels is not supported at the moment, but please make a request for implementation if you would need it.</p>
  97                                                 </description>
  98                                         </command-line-item>
  99                                         <command-line-item>
 100                                                 <parameters flag="--tmpdir"> <replacable>dir</replacable></parameters>
 101                                                 <description>
 102                                                         <p>Specify directory for temporary files.  See also --tmp*= and the environment variable <env-var name="SHAPESTMPDIR" />.</p>
 103                                                 </description>
 104                                         </command-line-item>
 105                                         <command-line-item>
 106                                                 <nosep-parameter flag="--tmp*=">bool</nosep-parameter>
 107                                                 <description>
 108                                                         <p>Permission to create directory for temporary files if it does not exist.  Defaults to no.  See also --tmpdir.</p>
 109                                                 </description>
 110                                         </command-line-item>
 111                                         <command-line-item id="needpath">
 112                                                 <parameters flag="--needpath"> <replacable>dir</replacable></parameters>
 113                                                 <nosep-parameter flag="-N">dir</nosep-parameter>
 114                                                 <description>
 115                                                         <p>Add <replacable>dir</replacable> to the end of the search path for language extension sources.  See also the environment variable <env-var name="SHAPESINPUTS" />.</p>
 116                                                 </description>
 117                                         </command-line-item>
 118                                         <command-line-item>
 119                                                 <parameters flag="--base"> <replacable>filenamebase</replacable></parameters>
 120                                                 <description>
 121                                                         <p>Specify the filename base to derive other filenames from.</p>
 122                                                 </description>
 123                                         </command-line-item>
 124                                         <command-line-item>
 125                                                 <parameters flag="--in"> <replacable>file</replacable></parameters>
 126                                                 <description>
 127                                                         <p>Specify the input source.  Defaults to the basename with the suffix <filename>.shape</filename> or <filename>.blank</filename> in the current directory.  Higher priority is given to the suffix <filename>.shape</filename>.</p>
 128                                                 </description>
 129                                         </command-line-item>
 130                                         <command-line-item>
 131                                                 <parameters flag="--prepend"> <replacable>str</replacable></parameters>
 132                                                 <description>
 133                                                         <p>Prepend the given string to the input source.</p>
 134                                                 </description>
 135                                         </command-line-item>
 136                                         <command-line-item>
 137                                                 <parameters flag="--out"> <replacable>file</replacable></parameters>
 138                                                 <description>
 139                                                         <p>Specify the destination file.  If the document <em>is not</em> split, this defaults to the basename with the suffix <filename>.pdf</filename> in the output directory.  If the document <em>is</em> split, this defaults to only the basename, as the suffix must be deduced automatically.  Not used in blank mode.</p>
 140                                                 </description>
 141                                         </command-line-item>
 142                                         <command-line-item>
 143                                                 <parameters flag="--labeldb"> <replacable>file</replacable></parameters>
 144                                                 <description>
 145                                                         <p>Specify the file where to store labels between iterations.  Defaults to the basename with the suffix <filename>.labels.pdf</filename> in the output directory.  Used in both shape and blank mode.</p>
 146                                                         <p>See also --iteration.</p>
 147                                                 </description>
 148                                         </command-line-item>
 149                                         <command-line-item>
 150                                                 <parameters flag="--afmout"> <replacable>file</replacable></parameters>
 151                                                 <description>
 152                                                         <p>Specify the file where to store generated font metrics, would there be any.  Defaults to the basename with the suffix <filename>.afm</filename> in the output directory.</p>
 153                                                 </description>
 154                                         </command-line-item>
 155                                         <command-line-item>
 156                                                 <parameters flag="--fontmetricspath"> <replacable>dir</replacable></parameters>
 157                                                 <nosep-parameter flag="-M">dir</nosep-parameter>
 158                                                 <description>
 159                                                         <p>Add <replacable>dir</replacable> to the end of the search path for font metrics.</p>
 160                                                 </description>
 161                                 </command-line-item>
 162                                         <command-line-item>
 163                                                 <nosep-parameter flag="--resources=">bool</nosep-parameter>
 164                                                 <description>
 165                                                         <p>Control access to files installed with the <str-Shapes /> program.  This applies both to language extensions and font metric files.  Defaults to true.</p>
 166                                                 </description>
 167                                         </command-line-item>
 168                                         <command-line-item>
 169                                                 <nosep-parameter flag="--iteration=">bool</nosep-parameter>
 170                                                 <description>
 171                                                         <p>If true, a file with cached <value name="TeX" /> labels will be created in the output directory, to be reused if the file is compiled again.  If false, no such file will be created, and no such file will be used.  Defaults to true unless the label database filename is undefined.</p>
 172                                                         <p>See also --labeldb.</p>
 173                                                 </description>
 174                                         </command-line-item>
 175                                         <command-line-item>
 176                                                 <parameters flag="&lt;stdin&gt;"></parameters>
 177                                                 <description>
 178                                                         <p>The special file <filename>stdin</filename> is used when the input source is not determined in any other way.  This means that the filename base must not be defined, so sometimes <filename>#shapes</filename> has to be used instead.</p>
 179                                                 </description>
 180                                         </command-line-item>
 181                                         <command-line-item>
 182                                                 <parameters flag="&lt;stdout&gt;"></parameters>
 183                                                 <description>
 184                                                         <p>Since the user may write charater data on the special file <filename>stdout</filename>, <filename>stdout</filename> cannot be used for the produced <str-PDF /> file.  This should not be a major inconvenience since the <str-PDF /> format is not suited for stream editing anyway.  Consider using the --out option when the input is taken from <filename>stdin</filename>.</p>
 185                                                 </description>
 186                                         </command-line-item>
 187                                         <command-line-item id="debuglog">
 188                                                 <parameters flag="--debuglog"> <replacable>file</replacable></parameters>
 189                                                 <parameters flag="--debuglog-stderr"></parameters>
 190                                                 <parameters flag="--debuglog-stdout"></parameters>
 191                                                 <description>
 192                                                         <p>Specify file for the user's debug log messages.</p>
 193                                                 </description>
 194                                         </command-line-item>
 195                                         <command-line-item id="mode">
 196                                                 <parameters flag="--blank"></parameters>
 197                                                 <parameters flag="--shape"></parameters>
 198                                                 <description>
 199                                                         <p>Select blank or shape mode (do not select mode based on the input filename suffix).</p>
 200                                                         <p>Blank mode is the default for input filenames with the <filename>.blank</filename> suffix, while shape mode is the default for input filenames with the <filename>.shape</filename> suffix.  Shape mode has precedence over blank mode when the mode cannot be determined from input filename suffix (including when input is read from a stream).</p>
 201                                                         <p>In blank mode, the program is not required to produce any graphics, and no result will be written to the output file or directory.  Any input filename must have the <filename>.blank</filename> suffix.</p>
 202                                                         <p>In shape mode, the program is required to produce graphics, which will be written to the output file or directory upon successful compilation.  Any input filename must have the <filename>.shape</filename> suffix.</p>
 203                                                 </description>
 204                                         </command-line-item>
 205                                 </command-line-option-list>
 206                         </body>
 207                 </section>
 208                 <section>
 209                         <title>Tolerances and other parameters</title>
 210                         <body>
 211                                 <command-line-option-list>
 212                                         <command-line-item>
 213                                                 <nosep-parameter flag="--seed=">s</nosep-parameter>
 214                                                 <description>
 215                                                         <p>Initializes the global random number generator by calling the srand function..</p>
 216                                                 </description>
 217                                         </command-line-item>
 218                                         <command-line-tolparam name="arcdelta" />
 219                                         <command-line-tolparam name="dtmin" />
 220                                         <command-line-item>
 221                                                 <nosep-parameter flag="--dtminerror=">bool</nosep-parameter>
 222                                                 <description>
 223                                                         <p>Control whether bumping up too short steplengths in integration along paths shall be considered an error.  See also --dtmin.</p>
 224                                                         <p><b>Rationale:</b> By default, it is considered an error if a length-measuring loop over one simple cubic spline requires too small steps.  The number of steps required depends on the arc-delta setting.  However, if changing arc-delta is not what one wants, and one cannot create the spline using more points, then a last resort is to inhibit the error using this option.  Note, however, that evaluating a program this way may be a process that does not terminate, practically speaking.</p>
 225                                                 </description>
 226                                         </command-line-item>
 227                                         <command-line-tolparam name="disttol" />
 228                                         <command-line-tolparam-remaining />
 229                                         <command-line-item>
 230                                                 <nosep-parameter flag="--fmguesserror=">bool</nosep-parameter>
 231                                                 <description>
 232                                                         <p>Control whether guessing font metrics for (more or less) strange characters shall be considered an error.</p>
 233                                                 </description>
 234                                         </command-line-item>
 235                                 </command-line-option-list>
 236                         </body>
 237                 </section>
 238                 <section>
 239                         <title>Verbosity</title>
 240                         <body>
 241                                 <command-line-option-list>
 242                                         <command-line-item>
 243                                                 <nosep-parameter flag="--bytecolumn=">bool</nosep-parameter>
 244                                                 <description>
 245                                                         <p>When true, report source file columns in bytes rather than complete <str-UTF-8 /> characters.  Defaults to false.</p>
 246                                                 </description>
 247                                         </command-line-item>
 248                                         <command-line-item>
 249                                                 <nosep-parameter flag="--unit=">unit-name</nosep-parameter>
 250                                                 <description>
 251                                                         <p>Set the unit to use for textual representation of lengths.  Defaults to cm.</p>
 252                                                 </description>
 253                                         </command-line-item>
 254                                         <command-line-item>
 255                                                 <nosep-parameter flag="--showfiles=">bool</nosep-parameter>
 256                                                 <description>
 257                                                         <p>Print the chain of used sources.</p>
 258                                                 </description>
 259                                         </command-line-item>
 260                                         <command-line-item>
 261                                                 <nosep-parameter flag="--stats=">bool</nosep-parameter>
 262                                                 <description>
 263                                                         <p>Control printing of execution statistics, such as memory and time usage.</p>
 264                                                 </description>
 265                                         </command-line-item>
 266                                         <command-line-item>
 267                                                 <parameters flag="--help"></parameters>
 268                                                 <description>
 269                                                         <p>Print a short help message and exit.  Note that this command line option cannot be combined with other usages of the compiler.</p>
 270                                                 </description>
 271                                         </command-line-item>
 272                                         <command-line-item>
 273                                                 <nosep-parameter flag="--i-format-prompt=">format</nosep-parameter>
 274                                                 <nosep-parameter flag="-?P">format</nosep-parameter>
 275                                                 <nosep-parameter flag="--i-format-show=">format</nosep-parameter>
 276                                                 <nosep-parameter flag="-?S">format</nosep-parameter>
 277                                                 <nosep-parameter flag="--i-format-file=">format</nosep-parameter>
 278                                                 <nosep-parameter flag="-?F">format</nosep-parameter>
 279                                                 <nosep-parameter flag="--i-format-eof=">format</nosep-parameter>
 280                                                 <nosep-parameter flag="-?E">format</nosep-parameter>
 281                                                 <description>
 282                                                         <p>Set format strings for the interaction in interactive mode.  Each format string is used to format a sequence number of the user input.</p>
 283                                                         <p>In the format string, the escape character <lexerregexp>\\</lexerregexp> followed by any of <lexerregexp>[ant%\\]</lexerregexp> is used to produce some special characters (when followed by other characters, the escape character is not given special meaning).  To format the sequence number a sequence starting with <lexerregexp>%</lexerregexp> and ending with <lexerregexp>[LR]</lexerregexp> is used.  Here, the final letter indicates <em>left</em> or <em>right</em> flush.  After the initial <lexerregexp>%</lexerregexp>, a prefix and a suffix string shall be specified.  The first character after the initial <lexerregexp>%</lexerregexp> specifies a string delimiter, and should appear two more times, thereby delimiting the prefix and suffix, respectively.  The final letter may be proceeded by a small, non-negative, number giving the width of the formatted number (including prefix and suffix).</p>
 284                                                         <p>The <em>prompt</em> string refers to the string printed when asking for user input (default: “<![CDATA[[%!#!!3R] ]]>”).  The <em>show</em> string refers to the string printed before a computed value is shown (default: “<![CDATA[%!#!!3R ⇒ ]]>”).  The <em>file</em> string refers to the string printed before names of files written to (default: “<![CDATA[#File: ]]>”).  The <em>bye</em> string refers to the string printed when reaching the end of the input stream, and the interactive mode is terminated (default: “<![CDATA[<<EOF>>\n]]>”).</p>
 285                                                 </description>
 286                                         </command-line-item>
 287                                 </command-line-option-list>
 288                         </body>
 289                 </section>
 290                 <section>
 291                         <title>Versions</title>
 292                         <body>
 293                                 <command-line-option-list>
 294                                         <command-line-item>
 295                                                 <nosep-parameter flag="--pdf-version=">mode-ver</nosep-parameter>
 296                                                 <nosep-parameter flag="-v">mode-ver</nosep-parameter>
 297                                                 <description>
 298                                                         <p>Set the highest <str-PDF /> version to use in output.  The <replacable>mode-ver</replacable> parameter shall begin with either of the letters <quote>e</quote> (error), <quote>w</quote> (warning), or <quote>s</quote> (silent).  The letter tells how the compiler shall react when it is not allowed to use a requested feature in the output, and must consider using a simpler replacement.  After the letter, a <str-PDF /> version, such as <quote>1.3</quote> shall follow.  Hence, for instance, <quote>w1.3</quote> is a valid <replacable>mode-ver</replacable> value.</p>
 299                                                         <p>Note that this setting affects the <em>highest</em> version to be used; <str-Shapes /> will mark the produced file with the lowest version number providing the features used.  Also note that the most common need for version 1.4 stems from the transparency groups used to merge a stroke with its arrowhead.</p>
 300                                                         <p>By default, the <str-PDF /> version is limited to 1.4, but this is likely to change in the future.</p>
 301                                                         <p>See also --tp.</p>
 302                                                 </description>
 303                                         </command-line-item>
 304                                         <command-line-item>
 305                                                 <nosep-parameter flag="--tp=">bool</nosep-parameter>
 306                                                 <description>
 307                                                         <p>Whether to allow the Kernel to use the transparent imaging model (requires <str-PDF /> version 1.4).  At the moment, this only affects whether to use a transparency group to merge an arrowhead with its stroke.  In many cases, disallowing this will effektively reduce the <str-PDF /> version of the output to 1.3 or below.  However, the main reason for this option to exist is that the <str-PDF /> viewer Adobe Reader prior to version 8 had a bug that caused a failure when printing.  Defaults to true.</p>
 308                                                         <p>See also --pdf-version.</p>
 309                                                 </description>
 310                                         </command-line-item>
 311                                         <command-line-item id="AllowSingletonPaths">
 312                                                 <nosep-parameter flag="--spot-pair=">bool</nosep-parameter>
 313                                                 <description>
 314                                                         <p>Not really being a version-related option, this at least affects the compatibility with some PDF-interpreting applications.  Determines whether the function <value name="spot" /> should generate closed singleton paths (more efficient) or paths between a pair of points at the same location (more compatible).  Defaults to false (that is, singleton).</p>
 315                                                 </description>
 316                                         </command-line-item>
 317                                         <command-line-item id="print-version">
 318                                                 <parameters flag="--version"></parameters>
 319                                                 <description>
 320                                                         <p>Print version information about the compiler, and exit.  The version information consists of a version string, a corresponding date, and a list of activated build options.  The meanings of the names identifying build options are explained in the <a part="install" id="install-depend/recommended">installation instructions</a>.</p>
 321                                                 </description>
 322                                         </command-line-item>
 323                                 </command-line-option-list>
 324                         </body>
 325                 </section>
 326                 <section>
 327                         <title>Preview</title>
 328                         <body>
 329                                 <p><str-Shapes /> can launch xpdf or invoke the MacOS <prog-name>open</prog-name> command to show the resulting graphics.  In a future version, it may be possible to specify an arbitrary command to be issued, which could look like this:</p>
 330 <command-line>
 331 shapes --viewer 'open -a TeXShop %' myfile.shape
 332 </command-line>
 333         <command-line-option-list>
 334                                         <command-line-item>
 335                                                 <parameters flag="--open"></parameters>
 336                                                 <description>
 337                                                         <p>Use the open program to open the result using a system default viewer for <str-PDF /> files.</p>
 338                                                 </description>
 339                                         </command-line-item>
 340                                         <command-line-item>
 341                                                 <parameters flag="--open-a"> <replacable>program</replacable></parameters>
 342                                                 <description>
 343                                                         <p>Like --open, but here the application to use is specified by the user.</p>
 344                                                 </description>
 345                                         </command-line-item>
 346                                         <command-line-item>
 347                                                 <parameters flag="--xpdf"></parameters>
 348                                                 <description>
 349                                                         <p>Use the xpdf program to preview the result.  The program is run in remote server mode.</p>
 350                                                         <p>In interactive mode with --split=no, the behavior is changed to that of --xpdf-reload after the first invocation.</p>
 351                                                 </description>
 352                                         </command-line-item>
 353                                         <command-line-item>
 354                                                 <parameters flag="--xpdf-remote"> <replacable>name</replacable></parameters>
 355                                                 <description>
 356                                                         <p>Set the name to use when running the xpdf program in remote mode.  Defaults to the output filename.</p>
 357                                                 </description>
 358                                         </command-line-item>
 359                                         <command-line-item>
 360                                                 <parameters flag="--xpdf-no-server"></parameters>
 361                                                 <description>
 362                                                         <p>Inhibit use of the remote server mode.  A new xpdf window will appear each time.</p>
 363                                                 </description>
 364                                         </command-line-item>
 365                                         <command-line-item>
 366                                                 <parameters flag="--xpdf-reload"></parameters>
 367                                                 <description>
 368                                                         <p>Make the xpdf server reload rather than raise.</p>
 369                                                 </description>
 370                                         </command-line-item>
 371                                         <command-line-item>
 372                                                 <parameters flag="--xpdf-quit"></parameters>
 373                                                 <description>
 374                                                         <p>Make the xpdf server quit rather than show your graphics.</p>
 375                                                 </description>
 376                                         </command-line-item>
 377                                 </command-line-option-list>
 378                         </body>
 379                 </section>
 380                 <section>
 381                         <title>User level debugging</title>
 382                         <body>
 383                                 <command-line-option-list>
 384                                         <command-line-item id="warn">
 385                                                 <parameters flag="--warn="><replacable>action</replacable></parameters>
 386                                                 <parameters flag="-W"><replacable>action</replacable></parameters>
 387                                                 <description>
 388                                                         <p>Specify action to take on warnings.  Valid actions are <quote>display</quote> (alias <quote>d</quote>), <quote>error</quote> (alias <quote>e</quote>), and <quote>ignore</quote> (alias <quote>i</quote>).  Defaults to <quote>display</quote>.</p>
 389                                                 </description>
 390                                         </command-line-item>
 391                                         <command-line-item id="interactive">
 392                                                 <parameters flag="--interactive"></parameters>
 393                                                 <parameters flag="-i"></parameters>
 394                                                 <description>
 395                                                         <p>Not primarily for debugging, but may be useful for learning the language, this make the compiler run in <em>interactive mode</em>.</p>
 396                                                         <p>In this mode, the output directory defaults to the directory for temporary files, and the output name defaults to <filename>#shapes.pdf</filename>.</p>
 397                                                         <p>The language semantics differs a bit from when the compiler operates in non-interactive mode.  Please refer to the language documentation for details.</p>
 398                                                         <p>Input is normally taken from <filename>stdin</filename>, and an external viewer is used to show drawable values, for instance:</p>
 399 <command-line>
 400   shapes -i --xpdf
 401 </command-line>
 402               <p>However, the mode is most useful in conjunction with a supporting editing environment that can provide fancy command line editing, input history, and inline display of graphics, <abbr-etc />.</p>
 403                                                         <p>With --split=no, the same file is replaced each time a drawable result is produced.  The other split modes will create separate files, numbered according to the input number (instead of the page number in the document catalog).</p>
 404                                                         <p>To change the format of prompts <abbr-et-c />, see the options starting with <em>--i-format-</em>.</p>
 405                                                 </description>
 406                                         </command-line-item>
 407                                         <command-line-item>
 408                                                 <nosep-parameter flag="--backtrace=">bool</nosep-parameter>
 409                                                 <description>
 410                                                         <p>Whether to print a backtrace when the program reports a runtime error.</p>
 411                                                 </description>
 412                                         </command-line-item>
 413                                         <command-line-item>
 414                                                 <parameters flag="--evaltrace"></parameters>
 415                                                 <description>
 416                                                         <p>Print information about each expression about to be evaluated.</p>
 417                                                 </description>
 418                                         </command-line-item>
 419                                         <command-line-item>
 420                                                 <parameters flag="--evalbacktrace"></parameters>
 421                                                 <description>
 422                                                         <p>As --evaltrace, but with a backtrace printed along with each expression.</p>
 423                                                 </description>
 424                                         </command-line-item>
 425                                 </command-line-option-list>
 426                         </body>
 427                 </section>
 428                 <section>
 429                         <title>Compiler developer debugging</title>
 430                         <body>
 431                                 <command-line-option-list>
 432                                         <command-line-item>
 433                                                 <parameters flag="--shapes-debug"></parameters>
 434                                                 <description>
 435                                                         <p>Turn on debug prints in the <str-Shapes /> lexer.</p>
 436                                                 </description>
 437                                         </command-line-item>
 438                                         <command-line-item>
 439                                                 <parameters flag="--yydebug"></parameters>
 440                                                 <description>
 441                                                         <p>Same as --shapes-debug.</p>
 442                                                 </description>
 443                                         </command-line-item>
 444                                         <command-line-item>
 445                                                 <parameters flag="--system-debug"></parameters>
 446                                                 <description>
 447                                                         <p>Turn on system debug messages.  The messages are written to <filename>stderr</filename>.</p>
 448                                                 </description>
 449                                         </command-line-item>
 450                                         <command-line-item>
 451                                                 <parameters flag="--afm-debug"></parameters>
 452                                                 <description>
 453                                                         <p>Turn on debug prints in the font metrics scanner.  Primarily for development use.  See also --afmmessages.</p>
 454                                                 </description>
 455                                         </command-line-item>
 456                                         <command-line-item>
 457                                                 <parameters flag="--afm-messages"></parameters>
 458                                                 <description>
 459                                                         <p>Turn on font metrics debug messages.  The messages are written to <filename>stderr</filename>.</p>
 460                                                 </description>
 461                                         </command-line-item>
 462                                         <command-line-item>
 463                                                 <parameters flag="--tex-debug"></parameters>
 464                                                 <description>
 465                                                         <p>Redirect the interaction output from <str-pdfLaTeX /> to <filename>stderr</filename> instead of a file with suffix <filename>.stdout</filename>.</p>
 466                                                 </description>
 467                                         </command-line-item>
 468                                         <command-line-item>
 469                                                 <parameters flag="--log-globals"></parameters>
 470                                                 <description>
 471                                                         <p>List content of the global environment (variable bindings, dynamic variables, and states) in the debug log file.  Every item in this list should be explained in the documentation.</p>
 472                                                 </description>
 473                                         </command-line-item>
 474                                         <command-line-item>
 475                                                 <nosep-parameter flag="--debugstep=">step</nosep-parameter>
 476                                                 <description>
 477                                                         <p>Set the debug step counter.  For compiler development only.</p>
 478                                                 </description>
 479                                         </command-line-item>
 480                                 </command-line-option-list>
 481                         </body>
 482                 </section>
 483                 <section>
 484                         <title>Garbage collection</title>
 485                         <body>
 486                                 <p>In the end, when garbage collection is implemented, there will be options for controlling the gc behavior here.  At the moment, there is only a dummy option here.</p>
 487                                 <command-line-option-list>
 488                                         <command-line-item>
 489                                                 <nosep-parameter flag="--memclean=">bool</nosep-parameter>
 490                                                 <description>
 491                                                         <p>Attempt to clean up memory before terminating the compilation process?  Defaults to true.</p>
 492                                                         <p><b>Rationale:</b> If the program seems to do stupid things after completing evaluation, it is possible that the cleaning-up process has caused a double free or access to freed memory.  While waiting for a fix, the problem can be handled by specifying this option, and thereby omitting the clean-up process entirely.</p>
 493                                                 </description>
 494                                         </command-line-item>
 495                                 </command-line-option-list>
 496                         </body>
 497                 </section>
 498                 <section>
 499                         <title>File requests</title>
 500                         <body>
 501                                 <p>Several file requests may be issued.  The answer to each will be written on a separate line on <filename>stdout</filename>, in the order of the requests.  After having answered to all requests, the program exits without compiling any input.  If the output filename is undefined in the presence of file requests, a dummy name will be used.</p>
 502                                 <command-line-option-list>
 503                                         <command-line-item>
 504                                                 <parameters flag="--which-in"/>
 505                                                 <description>
 506                                                         <p>Request the input source.</p>
 507                                                 </description>
 508                                         </command-line-item>
 509                                         <command-line-item>
 510                                                 <parameters flag="--which-out"/>
 511                                                 <description>
 512                                                         <p>Request the name of the output file.</p>
 513                                                 </description>
 514                                         </command-line-item>
 515                                         <command-line-item>
 516                                                 <parameters flag="--which-tmp"/>
 517                                                 <description>
 518                                                         <p>Request the name of the directory for temporary files.</p>
 519                                                 </description>
 520                                         </command-line-item>
 521                                         <command-line-item>
 522                                                 <parameters flag="--which-texjob"/>
 523                                                 <description>
 524                                                         <p>Request the <str-TeX /> job basename.</p>
 525                                                 </description>
 526                                         </command-line-item>
 527                                         <command-line-item>
 528                                                 <parameters flag="--which-labeldb"/>
 529                                                 <description>
 530                                                         <p>Request the label database to keep generated labels between iterations.</p>
 531                                                 </description>
 532                                         </command-line-item>
 533                                         <command-line-item>
 534                                                 <parameters flag="--which-afmout"/>
 535                                                 <description>
 536                                                         <p>Request the file where generated font metrics will be stored.</p>
 537                                                 </description>
 538                                         </command-line-item>
 539                                         <command-line-item>
 540                                                 <parameters flag="--which-TEXINPUTS"/>
 541                                                 <description>
 542                                                         <p>Request the environment variable <env-var name="TEXINPUTS" /> after any modifications made by <str-Shapes />.</p>
 543                                                 </description>
 544                                         </command-line-item>
 545                                         <command-line-item>
 546                                                 <parameters flag="--which-doc"/>
 547                                                 <description>
 548                                                         <p>Request the top index file of the locally installed <str-HTML /> documentation.</p>
 549                                                 </description>
 550                                         </command-line-item>
 551                                         <command-line-item>
 552                                                 <parameters flag="--which-share"/>
 553                                                 <description>
 554                                                         <p>Request the directory where support files are installed.</p>
 555                                                 </description>
 556                                         </command-line-item>
 557                                         <command-line-item>
 558                                                 <parameters flag="--which"> <replacable>source</replacable></parameters>
 559                                                 <description>
 560                                                         <p>Request a particular file.</p>
 561                                                 </description>
 562                                         </command-line-item>
 563                                 </command-line-option-list>
 564                         </body>
 565                 </section>
 566         </section>
 567
 568         <section>
 569                 <title>Environment variables</title>
 570                 <body>
 571                         <env-variable-list>
 572                                 <env-variable-item name="SHAPESINPUTS">
 573                                         <description>
 574                                                 <p>contains a search path used for requested source files.  It usually consists of directories with language extension files (with the <filename>.shext</filename> suffix).  On typical installations, the extension files shipped with the compiler are found using another mechanism.</p>
 575                                         </description>
 576                                 </env-variable-item>
 577                                 <env-variable-item name="SHAPESTMPDIR">
 578                                         <description>
 579                                                 <p>tells, when present, where to create temporary files.  In particular this concerns files related to label creation.  Note, however, that the label database file (with the <filename>.labels.pdf</filename> suffix) is put in the output directory since it is not considered a temporary file.  The environment variable is overridden by the --tmpdir command line option.  When undefined, it defaults to the current directory.</p>
 580                                         </description>
 581                                 </env-variable-item>
 582                                 <env-variable-item name="SHAPESFONTMETRICS">
 583                                         <description>
 584                                                 <p>tells where to search for font metrics files.  Font metrics for the standard fonts in <str-PDF /> are distributed with the compiler, and on typical installations these are found using another mechanism.</p>
 585                                         </description>
 586                                 </env-variable-item>
 587                                 <env-variable-item name="TEXINPUTS">
 588                                         <description>
 589                                                 <p>is manipulated locally to enable <str-TeX /> to find files located relative to the <str-Shapes /> source, although the <str-LaTeX /> source used for label creation may be placed in a different directory.</p>
 590                                         </description>
 591                                 </env-variable-item>
 592                         </env-variable-list>
 593                 </body>
 594         </section>
 595
 596         <section>
 597                 <title>Exit codes</title>
 598                 <body>
 599                         <exit-code-list />
 600                 </body>
 601         </section>
 602
 603         <section>
 604                 <title>Examples</title>
 605                 <section>
 606                         <title>Basic use</title>
 607                         <body>
 608                                 <p>Suppose there is a source called <filename>hi.shape</filename> in the current working directory.  Then there are three ways to specify this file to the compiler.  One may give the full filename:</p>
 609 <command-line>
 610   shapes hi.shape
 611 </command-line>
 612                                 <p>or just to the point your shell completion will take you:</p>
 613 <command-line>
 614   shapes hi.
 615 </command-line>
 616                                 <p>or exclude the suffix altogether:</p>
 617 <command-line>
 618   shapes hi
 619 </command-line>
 620                         </body>
 621                 </section>
 622                 <section>
 623                         <title>Use with xpdf</title>
 624                         <body>
 625                                 <p>To use the <prog-name class="other">xpdf</prog-name> program for preview, the previous example can be extended as:</p>
 626 <command-line>
 627   shapes --xpdf hi.shape
 628 </command-line>
 629                         </body>
 630                 </section>
 631                 <section>
 632                         <title>Use with stdin</title>
 633                         <body>
 634                                 <p>The following can be used to generate a small <str-PDF />-label from a <str-LaTeX /> string, without littering the current working directory with the <str-LaTeX />-related files:</p>
 635 <command-line>
 636 echo '[TeX &str-open;$x^{2}$&str-close;]' | shapes --tmpdir /tmp --out label.pdf
 637 </command-line>
 638                         </body>
 639                 </section>
 640                 <section>
 641                         <title>The test suite</title>
 642                         <body>
 643                                 <p>When testing the compiler on the bundled tests, the compiler is invoked something like this:</p>
 644 <command-line>
 645 shapes --resources=no --needpath ../../resources/extensions/ --fontmetricspath ../../resources/fontmetrics/ \
 646        --tmpdir tmp/ --outdir out/ hello.shape
 647 </command-line>
 648       <p>The first three options ensure that extension files and font metrics are not used from a previous installation.  This example assumes that environment variables are not used to provide search paths.</p>
 649                         </body>
 650                 </section>
 651         </section>
 652
 653
 654         <section>
 655                 <title>Author</title>
 656                 <body>
 657                         <p>Most of the code was written by Henrik Tidefelt.  Portability and distribution was provided by Gustaf Hendeby.</p>
 658                 </body>
 659         </section>
 660
 661         <section>
 662                 <title>See also</title>
 663                 <body>
 664                         <man-only>
 665                                 <p>Documentation of the <str-Shapes /> language should be possible to find on the web, but may also be installed here for local access:<expand-html-doc-index /></p>
 666                         </man-only>
 667                         <see-also-items>
 668                                 <see-also><manpage tool="xpdf" section="1" /></see-also>
 669                                 <see-also><manpage tool="open" section="1" /></see-also>
 670                         </see-also-items>
 671                 </body>
 672         </section>
 673
 674         <external>
 675                 <!--#include virtual="../algo-tol/tolerances.sxml" -->
 676                 <!--#include virtual="exit-codes.sxml" -->
 677         </external>
 678 </man>