doc/parts/man/index.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE man [
   3 <!ENTITY bullet "<char-bullet />">
   4 <!ENTITY str-open "<char-str-open />">
   5 <!ENTITY str-close "<char-str-close />">
   6 ]>
   7 <man>
   8         <manhead prog-name="shapes"
   9                                          section="1"
  10                                          modification-date=<!--#expand-next-string-->"$(MODIFICATION_DATE)">
  11                 <left-footer>Tiddes</left-footer>
  12                 <center-header>The <str-Shapes /> language compiler</center-header>
  13                 <description>
  14                         <p>Man page descripting the commad line interface of the compiler.</p>
  15                 </description>
  16                 <meta-selflink><part-href name="man" /></meta-selflink>
  17                 <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  18                 <html-doc-index href=<!--#expand-next-string-->"$(HTML_DOC_DIR)/index.html" />
  19         </manhead>
  20
  21         <section>
  22                 <title>Name</title>
  23                 <body>
  24                         <p>shapes — Compile a <str-Shapes /> source to <str-PDF />.</p>
  25                 </body>
  26         </section>
  27
  28         <section>
  29                 <title>Synopsis</title>
  30                 <body>
  31                         <synopsis-table>
  32                                 <synopsis-case><prog-name>shapes</prog-name> <synatxname>option</synatxname><bnf>*</bnf> <replacable>source</replacable></synopsis-case>
  33                                 <synopsis-case><prog-name>shapes</prog-name> <synatxname>option</synatxname><bnf>*</bnf></synopsis-case>
  34                                 <synopsis-case><prog-name>shapes</prog-name> <bnf>(</bnf> <synatxname>options</synatxname> <bnf>|</bnf> <synatxname>file-request</synatxname> <bnf>)*</bnf></synopsis-case>
  35                         </synopsis-table>
  36                 </body>
  37         </section>
  38
  39         <section>
  40                 <title>Description</title>
  41                 <body>
  42                         <p><prog-name>shapes</prog-name> compiles a source file written in the <str-Shapes /> language (with file name extension <filename>shape</filename>).  On success, this results in a <str-PDF /> file containing a viewable representation of the graphics described by the source.</p>
  43                 </body>
  44         </section>
  45
  46         <section>
  47                 <title>Command line options</title>
  48                 <top>
  49                         <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>
  50                         <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>
  51                 </top>
  52                 <section>
  53                         <title>Files</title>
  54                         <body>
  55                                 <command-line-option-list>
  56                                         <command-line-item>
  57                                                 <parameters flag="source"></parameters>
  58                                                 <description>
  59                                                         <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>; 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> suffix), which in turn provides names for all other files involved.</p>
  60                                                 </description>
  61                                         </command-line-item>
  62                                         <command-line-item>
  63                                                 <parameters flag="--outdir"> <replacable>dir</replacable></parameters>
  64                                                 <description>
  65                                                         <p>Specify directory for products.  Defaults to current working directory.</p>
  66                                                 </description>
  67                                         </command-line-item>
  68                                         <command-line-item>
  69                                                 <nosep-parameter flag="--split=">no/flat/dir</nosep-parameter>
  70                                                 <description>
  71                                                         <p>Determines how to store the pages of the produced document catalog.</p>
  72                                                         <p>When <em>no</em>:  One file with many pages is created.</p>
  73                                                         <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 extension, by adding the extension <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>
  74                                                         <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>
  75                                                         <p>Defaults to <em>no</em>.</p>
  76                                                         <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>
  77                                                 </description>
  78                                         </command-line-item>
  79                                         <command-line-item>
  80                                                 <parameters flag="--tmpdir"> <replacable>dir</replacable></parameters>
  81                                                 <description>
  82                                                         <p>Specify directory for temporary files.  See also --tmp*= and the environment variable SHAPESTMPDIR.</p>
  83                                                 </description>
  84                                         </command-line-item>
  85                                         <command-line-item>
  86                                                 <nosep-parameter flag="--tmp*=">bool</nosep-parameter>
  87                                                 <description>
  88                                                         <p>Permission to create directory for temporary files if it does not exist.  Defaults to no.  See also --tmpdir.</p>
  89                                                 </description>
  90                                         </command-line-item>
  91                                         <command-line-item>
  92                                                 <parameters flag="--needpath"> <replacable>dir</replacable></parameters>
  93                                                 <nosep-parameter flag="-N">dir</nosep-parameter>
  94                                                 <description>
  95                                                         <p>Add <replacable>dir</replacable> to the end of the search path for language extension sources.  See also the environment variable SHAPESINPUTS.</p>
  96                                                 </description>
  97                                         </command-line-item>
  98                                         <command-line-item>
  99                                                 <parameters flag="--base"> <replacable>filenamebase</replacable></parameters>
 100                                                 <description>
 101                                                         <p>Specify the filename base to derive other filenames from.</p>
 102                                                 </description>
 103                                         </command-line-item>
 104                                         <command-line-item>
 105                                                 <parameters flag="--in"> <replacable>file</replacable></parameters>
 106                                                 <description>
 107                                                         <p>Specify the input source.  Defaults to the basename with the suffix <filename>.shape</filename> in the current directory.</p>
 108                                                 </description>
 109                                         </command-line-item>
 110                                         <command-line-item>
 111                                                 <parameters flag="--prepend"> <replacable>str</replacable></parameters>
 112                                                 <description>
 113                                                         <p>Prepend the given string to the input source.</p>
 114                                                 </description>
 115                                         </command-line-item>
 116                                         <command-line-item>
 117                                                 <parameters flag="--out"> <replacable>file</replacable></parameters>
 118                                                 <description>
 119                                                         <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.</p>
 120                                                 </description>
 121                                         </command-line-item>
 122                                         <command-line-item>
 123                                                 <parameters flag="--labeldb"> <replacable>file</replacable></parameters>
 124                                                 <description>
 125                                                         <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.</p>
 126                                                 </description>
 127                                         </command-line-item>
 128                                         <command-line-item>
 129                                                 <parameters flag="--afmout"> <replacable>file</replacable></parameters>
 130                                                 <description>
 131                                                         <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>
 132                                                 </description>
 133                                         </command-line-item>
 134                                         <command-line-item>
 135                                                 <parameters flag="--fontmetricspath"> <replacable>dir</replacable></parameters>
 136                                                 <nosep-parameter flag="-M">dir</nosep-parameter>
 137                                                 <description>
 138                                                         <p>Add <replacable>dir</replacable> to the end of the search path for font metrics.</p>
 139                                                 </description>
 140                                 </command-line-item>
 141                                         <command-line-item>
 142                                                 <nosep-parameter flag="--resources=">bool</nosep-parameter>
 143                                                 <description>
 144                                                         <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>
 145                                                 </description>
 146                                         </command-line-item>
 147                                         <command-line-item>
 148                                                 <nosep-parameter flag="--iteration=">bool</nosep-parameter>
 149                                                 <description>
 150                                                         <p>If true, a file will labels will be created in the output directory, to be reused if the file is compiled again.  Defaults to true unless the label database filename is undefined.</p>
 151                                                 </description>
 152                                         </command-line-item>
 153                                         <command-line-item>
 154                                                 <parameters flag="&lt;stdin&gt;"></parameters>
 155                                                 <description>
 156                                                         <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>
 157                                                 </description>
 158                                         </command-line-item>
 159                                         <command-line-item>
 160                                                 <parameters flag="&lt;stdout&gt;"></parameters>
 161                                                 <description>
 162                                                         <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>
 163                                                 </description>
 164                                         </command-line-item>
 165                                         <command-line-item>
 166                                                 <parameters flag="--debuglog"> <replacable>file</replacable></parameters>
 167                                                 <parameters flag="--debuglog-stderr"></parameters>
 168                                                 <parameters flag="--debuglog-stdout"></parameters>
 169                                                 <description>
 170                                                         <p>Specify file for the user's debug log messages.</p>
 171                                                 </description>
 172                                         </command-line-item>
 173                                 </command-line-option-list>
 174                         </body>
 175                 </section>
 176                 <section>
 177                         <title>Tolerances and other parameters</title>
 178                         <body>
 179                                 <command-line-option-list>
 180                                         <command-line-item>
 181                                                 <nosep-parameter flag="--seed=">s</nosep-parameter>
 182                                                 <description>
 183                                                         <p>Initializes the global random number generator by calling the srand function..</p>
 184                                                 </description>
 185                                         </command-line-item>
 186                                         <command-line-tolparam name="arcdelta" />
 187                                         <command-line-tolparam name="dtmin" />
 188                                         <command-line-item>
 189                                                 <nosep-parameter flag="--dtminerror=">bool</nosep-parameter>
 190                                                 <description>
 191                                                         <p>Control whether bumping up too short steplengths in integration along paths shall be considered an error.  See also --dtmin.</p>
 192                                                         <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>
 193                                                 </description>
 194                                         </command-line-item>
 195                                         <command-line-tolparam-remaining />
 196                                         <command-line-item>
 197                                                 <nosep-parameter flag="--fmguesserror=">bool</nosep-parameter>
 198                                                 <description>
 199                                                         <p>Control whether guessing font metrics for (more or less) strange characters shall be considered an error.</p>
 200                                                 </description>
 201                                         </command-line-item>
 202                                 </command-line-option-list>
 203                         </body>
 204                 </section>
 205                 <section>
 206                         <title>Verbosity</title>
 207                         <body>
 208                                 <command-line-option-list>
 209                                         <command-line-item>
 210                                                 <nosep-parameter flag="--bytecolumn=">bool</nosep-parameter>
 211                                                 <description>
 212                                                         <p>When true, report source file columns in bytes rather than complete <str-UTF-8 /> characters.  Defaults to false.</p>
 213                                                 </description>
 214                                         </command-line-item>
 215                                         <command-line-item>
 216                                                 <nosep-parameter flag="--unit=">unit-name</nosep-parameter>
 217                                                 <description>
 218                                                         <p>Set the unit to use for textual representation of lengths.  Defaults to cm.</p>
 219                                                 </description>
 220                                         </command-line-item>
 221                                         <command-line-item>
 222                                                 <nosep-parameter flag="--showfiles=">bool</nosep-parameter>
 223                                                 <description>
 224                                                         <p>Print the chain of used sources.</p>
 225                                                 </description>
 226                                         </command-line-item>
 227                                         <command-line-item>
 228                                                 <nosep-parameter flag="--stats=">bool</nosep-parameter>
 229                                                 <description>
 230                                                         <p>Control printing of execution statistics, such as memory and time usage.</p>
 231                                                 </description>
 232                                         </command-line-item>
 233                                 </command-line-option-list>
 234                         </body>
 235                 </section>
 236                 <section>
 237                         <title>Versions</title>
 238                         <body>
 239                                 <command-line-option-list>
 240                                         <command-line-item>
 241                                                 <nosep-parameter flag="--pdf-version=">mode-ver</nosep-parameter>
 242                                                 <nosep-parameter flag="-v">mode-ver</nosep-parameter>
 243                                                 <description>
 244                                                         <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>
 245                                                         <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>
 246                                                         <p>By default, the <str-PDF /> version is limited to 1.4, but this is likely to change in the future.</p>
 247                                                         <p>See also --tp.</p>
 248                                                 </description>
 249                                         </command-line-item>
 250                                         <command-line-item>
 251                                                 <nosep-parameter flag="--tp=">bool</nosep-parameter>
 252                                                 <description>
 253                                                         <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>
 254                                                         <p>See also --pdf-version.</p>
 255                                                 </description>
 256                                         </command-line-item>
 257                                         <command-line-item id="AllowSingletonPaths">
 258                                                 <nosep-parameter flag="--spot-pair=">bool</nosep-parameter>
 259                                                 <description>
 260                                                         <p>Not really being a version-related option, this at least affects the compatibility with some PDF-interpreting applications.  Determines whether the function <binding 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>
 261                                                 </description>
 262                                         </command-line-item>
 263                                         <command-line-item>
 264                                                 <parameters flag="--version"></parameters>
 265                                                 <description>
 266                                                         <p>Print version information about the compiler, and exit.</p>
 267                                                 </description>
 268                                         </command-line-item>
 269                                 </command-line-option-list>
 270                         </body>
 271                 </section>
 272                 <section>
 273                         <title>Preview</title>
 274                         <body>
 275                                 <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>
 276 <command-line>
 277 shapes --viewer 'open -a TeXShop %' myfile.shapes
 278 </command-line>
 279         <command-line-option-list>
 280                                         <command-line-item>
 281                                                 <parameters flag="--open"></parameters>
 282                                                 <description>
 283                                                         <p>Use the open program to open the result using a system default viewer for <str-PDF /> files.</p>
 284                                                 </description>
 285                                         </command-line-item>
 286                                         <command-line-item>
 287                                                 <parameters flag="--open-a"> <replacable>program</replacable></parameters>
 288                                                 <description>
 289                                                         <p>Like --open, but here the application to use is specified by the user.</p>
 290                                                 </description>
 291                                         </command-line-item>
 292                                         <command-line-item>
 293                                                 <parameters flag="--xpdf"></parameters>
 294                                                 <description>
 295                                                         <p>Use the xpdf program to preview the result.  The program is run in remote server mode.</p>
 296                                                 </description>
 297                                         </command-line-item>
 298                                         <command-line-item>
 299                                                 <parameters flag="--xpdf-remote"> <replacable>name</replacable></parameters>
 300                                                 <description>
 301                                                         <p>Set the name to use when running the xpdf program in remote mode.  Defaults to the output filename.</p>
 302                                                 </description>
 303                                         </command-line-item>
 304                                         <command-line-item>
 305                                                 <parameters flag="--xpdf-no-server"></parameters>
 306                                                 <description>
 307                                                         <p>Inhibit use of the remote server mode.  A new xpdf window will appear each time.</p>
 308                                                 </description>
 309                                         </command-line-item>
 310                                         <command-line-item>
 311                                                 <parameters flag="--xpdf-reload"></parameters>
 312                                                 <description>
 313                                                         <p>Make the xpdf server reload rather than raise.</p>
 314                                                 </description>
 315                                         </command-line-item>
 316                                         <command-line-item>
 317                                                 <parameters flag="--xpdf-quit"></parameters>
 318                                                 <description>
 319                                                         <p>Make the xpdf server quit rather than show your graphics.</p>
 320                                                 </description>
 321                                         </command-line-item>
 322                                 </command-line-option-list>
 323                         </body>
 324                 </section>
 325                 <section>
 326                         <title>User level debugging</title>
 327                         <body>
 328                                 <command-line-option-list>
 329                                         <command-line-item>
 330                                                 <nosep-parameter flag="--backtrace=">bool</nosep-parameter>
 331                                                 <description>
 332                                                         <p>Whether to print a backtrace when the program reports a runtime error.</p>
 333                                                 </description>
 334                                         </command-line-item>
 335                                         <command-line-item>
 336                                                 <parameters flag="--evaltrace"></parameters>
 337                                                 <description>
 338                                                         <p>Print information about each expression about to be evaluated.</p>
 339                                                 </description>
 340                                         </command-line-item>
 341                                         <command-line-item>
 342                                                 <parameters flag="--evalbacktrace"></parameters>
 343                                                 <description>
 344                                                         <p>As --evaltrace, but with a backtrace printed along with each expression.</p>
 345                                                 </description>
 346                                         </command-line-item>
 347                                 </command-line-option-list>
 348                         </body>
 349                 </section>
 350                 <section>
 351                         <title>Compiler developer debugging</title>
 352                         <body>
 353                                 <command-line-option-list>
 354                                         <command-line-item>
 355                                                 <parameters flag="--shapes-debug"></parameters>
 356                                                 <description>
 357                                                         <p>Turn on debug prints in the <str-Shapes /> lexer.</p>
 358                                                 </description>
 359                                         </command-line-item>
 360                                         <command-line-item>
 361                                                 <parameters flag="--yydebug"></parameters>
 362                                                 <description>
 363                                                         <p>Same as --shapesdebug.</p>
 364                                                 </description>
 365                                         </command-line-item>
 366                                         <command-line-item>
 367                                                 <parameters flag="--system-debug"></parameters>
 368                                                 <description>
 369                                                         <p>Turn on system debug messages.  The messages are written to <filename>stderr</filename>.</p>
 370                                                 </description>
 371                                         </command-line-item>
 372                                         <command-line-item>
 373                                                 <parameters flag="--afm-debug"></parameters>
 374                                                 <description>
 375                                                         <p>Turn on debug prints in the font metrics scanner.  Primarily for development use.  See also --afmmessages.</p>
 376                                                 </description>
 377                                         </command-line-item>
 378                                         <command-line-item>
 379                                                 <parameters flag="--afm-messages"></parameters>
 380                                                 <description>
 381                                                         <p>Turn on font metrics debug messages.  The messages are written to <filename>stderr</filename>.</p>
 382                                                 </description>
 383                                         </command-line-item>
 384                                         <command-line-item>
 385                                                 <parameters flag="--tex-debug"></parameters>
 386                                                 <description>
 387                                                         <p>Redirect the interaction output from <str-pdfLaTeX /> to <filename>stderr</filename> instead of a file with suffix <filename>.stdout</filename>.</p>
 388                                                 </description>
 389                                         </command-line-item>
 390                                         <command-line-item>
 391                                                 <parameters flag="--log-globals"></parameters>
 392                                                 <description>
 393                                                         <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>
 394                                                 </description>
 395                                         </command-line-item>
 396                                         <command-line-item>
 397                                                 <nosep-parameter flag="--debugstep=">step</nosep-parameter>
 398                                                 <description>
 399                                                         <p>Set the debug step counter.  For compiler development only.</p>
 400                                                 </description>
 401                                         </command-line-item>
 402                                 </command-line-option-list>
 403                         </body>
 404                 </section>
 405                 <section>
 406                         <title>Garbage collection</title>
 407                         <body>
 408                                 <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>
 409                                 <command-line-option-list>
 410                                         <command-line-item>
 411                                                 <nosep-parameter flag="--memclean=">bool</nosep-parameter>
 412                                                 <description>
 413                                                         <p>Attempt to clean up memory before terminating the compilation process?  Defaults to true.</p>
 414                                                         <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>
 415                                                 </description>
 416                                         </command-line-item>
 417                                 </command-line-option-list>
 418                         </body>
 419                 </section>
 420                 <section>
 421                         <title>File requests</title>
 422                         <body>
 423                                 <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>
 424                                 <command-line-option-list>
 425                                         <command-line-item>
 426                                                 <parameters flag="--which-in"/>
 427                                                 <description>
 428                                                         <p>Request the input source.</p>
 429                                                 </description>
 430                                         </command-line-item>
 431                                         <command-line-item>
 432                                                 <parameters flag="--which-out"/>
 433                                                 <description>
 434                                                         <p>Request the name of the output file.</p>
 435                                                 </description>
 436                                         </command-line-item>
 437                                         <command-line-item>
 438                                                 <parameters flag="--which-tmp"/>
 439                                                 <description>
 440                                                         <p>Request the name of the directory for temporary files.</p>
 441                                                 </description>
 442                                         </command-line-item>
 443                                         <command-line-item>
 444                                                 <parameters flag="--which-texjob"/>
 445                                                 <description>
 446                                                         <p>Request the <str-TeX /> job basename.</p>
 447                                                 </description>
 448                                         </command-line-item>
 449                                         <command-line-item>
 450                                                 <parameters flag="--which-labeldb"/>
 451                                                 <description>
 452                                                         <p>Request the label database to keep generated labels between iterations.</p>
 453                                                 </description>
 454                                         </command-line-item>
 455                                         <command-line-item>
 456                                                 <parameters flag="--which-afmout"/>
 457                                                 <description>
 458                                                         <p>Request the file where generated font metrics will be stored.</p>
 459                                                 </description>
 460                                         </command-line-item>
 461                                         <command-line-item>
 462                                                 <parameters flag="--which-TEXINPUTS"/>
 463                                                 <description>
 464                                                         <p>Request the environment variable TEXINPUTS after any modifications made by <str-Shapes />.</p>
 465                                                 </description>
 466                                         </command-line-item>
 467                                         <command-line-item>
 468                                                 <parameters flag="--which-doc"/>
 469                                                 <description>
 470                                                         <p>Request the top index file of the locally installed <str-HTML /> documentation.</p>
 471                                                 </description>
 472                                         </command-line-item>
 473                                         <command-line-item>
 474                                                 <parameters flag="--which"> <replacable>source</replacable></parameters>
 475                                                 <description>
 476                                                         <p>Request a particular file.</p>
 477                                                 </description>
 478                                         </command-line-item>
 479                                 </command-line-option-list>
 480                         </body>
 481                 </section>
 482         </section>
 483
 484         <section>
 485                 <title>Environment variables</title>
 486                 <body>
 487                         <env-variable-list>
 488                                 <env-variable-item>
 489                                         <name>SHAPESINPUTS</name>
 490                                         <description>
 491                                                 <p>contains a search path used for requested source files.  It usually consists of directories with language extension files (with the <filename>.shext</filename> extension).  On typical installations, the extension files shipped with the compiler are found using another mechanism.</p>
 492                                         </description>
 493                                 </env-variable-item>
 494                                 <env-variable-item>
 495                                         <name>SHAPESTMPDIR</name>
 496                                         <description>
 497                                                 <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> extension) 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>
 498                                         </description>
 499                                 </env-variable-item>
 500                                 <env-variable-item>
 501                                         <name>SHAPESFONTMETRICS</name>
 502                                         <description>
 503                                                 <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>
 504                                         </description>
 505                                 </env-variable-item>
 506                                 <env-variable-item>
 507                                         <name>TEXINPUTS</name>
 508                                         <description>
 509                                                 <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>
 510                                         </description>
 511                                 </env-variable-item>
 512                         </env-variable-list>
 513                 </body>
 514         </section>
 515
 516         <section>
 517                 <title>Exit codes</title>
 518                 <body>
 519                         <exit-code-list />
 520                 </body>
 521         </section>
 522
 523         <section>
 524                 <title>Examples</title>
 525                 <section>
 526                         <title>Basic use</title>
 527                         <body>
 528                                 <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>
 529 <command-line>
 530   shapes hi.shape
 531 </command-line>
 532                                 <p>or just to the point your shell completion will take you:</p>
 533 <command-line>
 534   shapes hi.
 535 </command-line>
 536                                 <p>or exclude the suffix altogether:</p>
 537 <command-line>
 538   shapes hi
 539 </command-line>
 540                         </body>
 541                 </section>
 542                 <section>
 543                         <title>Use with xpdf</title>
 544                         <body>
 545                                 <p>To use the <prog-name class="other">xpdf</prog-name> program for preview, the previous example can be extended as:</p>
 546 <command-line>
 547   shapes --xpdf hi.shape
 548 </command-line>
 549                         </body>
 550                 </section>
 551                 <section>
 552                         <title>Use with stdin</title>
 553                         <body>
 554                                 <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>
 555 <command-line>
 556 echo '&bullet;page &lt;&lt; (TeX &str-open;$x^{2}$&str-close;)' | shapes --tmpdir /tmp --out label.pdf
 557 </command-line>
 558                         </body>
 559                 </section>
 560                 <section>
 561                         <title>The test suite</title>
 562                         <body>
 563                                 <p>When testing the compiler on the bundled tests, the compiler is invoked something like this:</p>
 564 <command-line>
 565 shapes --resources=no --needpath ../../resources/extensions/ --fontmetricspath ../../resources/fontmetrics/ \
 566        --tmpdir tmp/ --outdir out/ hello.shape
 567 </command-line>
 568       <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>
 569                         </body>
 570                 </section>
 571         </section>
 572
 573
 574         <section>
 575                 <title>Author</title>
 576                 <body>
 577                         <p>Most of the code was written by Henrik Tidefelt.  Portability and distribution was provided by Gustaf Hendeby.</p>
 578                 </body>
 579         </section>
 580
 581         <section>
 582                 <title>See also</title>
 583                 <body>
 584                         <man-only>
 585                                 <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>
 586                         </man-only>
 587                         <see-also-items>
 588                                 <see-also><manpage tool="xpdf" section="1" /></see-also>
 589                                 <see-also><manpage tool="open" section="1" /></see-also>
 590                         </see-also-items>
 591                 </body>
 592         </section>
 593
 594         <external>
 595                 <!--#include virtual="../algo-tol/tolerances.sxml" -->
 596                 <!--#include virtual="exit-codes.sxml" -->
 597         </external>
 598 </man>