  User manual for LPU
  John R. Schrader jrschrader@mainz-online.de
  v0.9-24, August 21 2000

  This document describes the use of LPU.
  ______________________________________________________________________

  Table of Contents


  1. Introduction

  2. General description

     2.1 Some definitions
     2.2 Functional description
     2.3 The command line
     2.4 The DEV file
     2.5 The PAR file
     2.6 The TAB file

  3. The reference section

     3.1 The LPU commands
        3.1.1 Jump targets
        3.1.2 The dot commands
        3.1.3 Quoted lines
        3.1.4 Database support
        3.1.5 Support for EPS files
        3.1.6 Preprocessor instructions
     3.2 Text replacement
     3.3 Evaluating expressions

  4. Other features

     4.1 The debugger
     4.2 Tracing

  5. Closing remarks



  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn

  The Label Printing Utility (LPU) is a tool for creation of forms,
  labels and so on.

  In the beginning, LPU was developed on a Atari ST with a K&R-C-
  Compiler.  Later, it was ported to ANSI-C under QNX, then to Linux.

  Current development takes place under Linux.

  Written in pure ANSI-C, it should compile without problems on almost
  all flavors of UNIX, and - with a minimum of changes - many other
  systems too.  LPU is known to build under Linux and QNX.

  Currently, the primary use of LPU is the creation of simple labels and
  forms using mainly text information.

  LPU is able to create single labels, a number of identical labels
  (visiting cards etc.), or a number of similar, but slightly differing
  labels (video cassette labels etc.). The third kind of labels can be
  created using an import interface for structured text information.

  22..  GGeenneerraall ddeessccrriippttiioonn

  22..11..  SSoommee ddeeffiinniittiioonnss

  Some keywords are used throughout this document, which may be unknown
  (or known with another meaning) outside LPU.  So here is a description
  of them:


     DDOOTT
        Within LPU, all positions and distances are calculated in the
        unit DOT.  A DOT is currently defined as a tenth of a point
        (1/720").


     UUNNIITT
        A UNIT is an integer or float value with an optional unit.

        The unit can be any of


       `c' for centimeter

       `m' for millimeter

       `i' for inch

       `r' for row

        A missing unit is interpreted as DOT.

        A UNIT is always directly converted to DOTs.


     NNUUMM
        Datatype T_NUM, numerical.

        This is an integer value, 32bit on most systems.


     FFLLTT
        Datatype T_FLT, float.

        This is a float value, 64bit double on most systems.


     SSTTRR
        Datatype T_STR, string.

        This is a text string value, the maximum length is not exactly
        defined at this time.


  22..22..  FFuunnccttiioonnaall ddeessccrriippttiioonn

  LPU reads its commands from one or more command files, executes the
  commands and creates postscript code as output.

  If no command files are given, commands are taken from stdin.

  If no output file is specified, output is sent to stdout.

  LPU requires two additional support files:



  1. a file with device specific information (see ``The DEV file'').

  2. a file with form and label definitions (see ``The TAB file'').

  Additionally, a file with general parameters may be used (see ``The
  PAR file'').


  22..33..  TThhee ccoommmmaanndd lliinnee

  LPU is called in the following way:



         lpu { OPTION } { SOURCE-FILE }




  Currently, the following options are known:


     ---- This option tells LPU to take commands from STDIN instead of a
        file; it has no effect if any SOURCE-FILEs are given on the
        command line.


     --bb tells LPU to run in batch mode.

        Within this mode, some LPU commands behave differently.  The
        system function `$batchmode' may be used within programs to
        check if LPU is running in this mode, and to react in a
        convenient way.


     --ddDDEEVVFFIILLEE
        specifies a different name for the DEV file.  The default name
        is `lpu.dev'.


     --ff creates a thin frame around every label.

        This is useful for test purposes or as a means to cut the label
        out of a plain sheet of paper.


     --hh Shows a list of all known options.


     --jjCCOOUUNNTT
        tells LPU to skip the first COUNT labels on the first sheet.

        This is useful if you want to continue filling a partly used
        sheet.


     --ooOOUUTTFFIILLEE
        tells LPU to send the output to file OUTFILE.  If this option is
        missing, output is sent to STDOUT.


     --ppPPAARRFFIILLEE
        specifies a different name for the PAR file.  The default name
        is `lpu.par'.


     --ssSSYYMMBBOOLL==[[VVAALLUUEE]]
        creates a global variable SYMBOL with an optional value VALUE;
        the type of the variable is T_STR.

        If VALUE is missing, an empty string is assigned to SYMBOL.


     --ttTTAABBFFIILLEE
        specifies a different name for the TAB file.  The default name
        is `lpu.tab'.


     --vv[[LLEEVVEELL]]
        specifies a debug level. LEVEL may be a number between `0' and
        `9', the default (if LEVEL is missing) is `1'.  Without this
        option, or if LEVEL is `0', no debug information is created, `1'
        creates only little information, and `9' as much as available.

        All debug information - like all error messages - are directed
        to stderr.

  SOURCE-FILE specifies the name of an LPU command file. If the
  extension is missing `.lpu' is assumed.

  Any number of SOURCE-FILEs may be given on the command line. They are
  executed in the order they are given on the command line.

  If no SOURCE-FILE is given, then commands are taken from STDIN; in
  this case, option `--' should be used.

  LPU will search for the DEV, TAB and PAR files (the original names or
  the names set by the options `-d', `-t' and `-p') in the following
  order:


    in the current working directory

    in `$HOME/.lpu/'

    in `$LPUDIR', if this symbol is defined


  22..44..  TThhee DDEEVV ffiillee

  This file contains information about the used output device.  It
  defines paper sizes, fonts etc.

  It is a pure text file, and the information is organized line by line.

  Empty lines, and lines which start with a `;' are ignored.

  Commands start with a `%', followed by a keyword and optional
  parameters.

  The following commands are defined:


     %%DDeevviiccee IIDD TTYYPPEE CCOOMMMMEENNTT
        specifies the output device.

        ID is an identifier for the device.

        TYPE is the type of the device. Currently, the following device
        types are defined:


        SSEEQQ
           sequential output.


        RRAANN
           random output.


        Currently, LPU requires the device type to be `RAN'.

        COMMENT is a short description of the device.


     %%AAddjjuusstt XXNNUULLLL YYNNUULLLL
        this defines offsets for adjustment of the output device.

        The values XNULL and YNULL (measured in DOT) will be added to
        every coordinate on the page. So a positive value shifts the
        output to the right and bottom, while a negative value shifts to
        the left and top.

        The LPU distribution contains the program 'messen.lpu', which
        can be used to print a test sheet for measuring these offsets.


     %%PPaaggee IIDD XXMMAAXX YYMMAAXX LLMM RRMM TTMM BBMM
        defines a new page format.

        ID is a unique name for the format.  XMAX and YMAX define the
        total size of the format in DOT.

        LM, RM, TM and BM specify the left, right, top and bottom
        margin.  These margins exclude the non-printable areas of the
        page.

        [Author's note: I would appreciate any sending in of other
        format definitions (especially for formats used outside
        Germany), which I will integrate into the distribution.]


     %%PPssFFoonntt IIDD PPOOIINNTTSS AATTTTRR RREELLWWIIDDTTHH FFOONNTT--NNAAMMEE

     %%PPssFFoonntt IIDD PPOOIINNTTSS AATTTTRR @@FFOONNTT--NNAAMMEE
        defines a new postscript font.

        ID is an internal font name, which will be used inside LPU (for
        example within the .style command).

        POINTS defines the font size in points. If the font size is
        variable (as with true-type fonts), a `*' can be supplied
        instead.

        ATTR is a list of font attributes, which may be constructed from
        the following set of characters:


        NN  normal.  Disables all other attributes.  May be needed as a
           place holder, if no other attributes are specified.


        BB  bold.


        II  italic.


        UU  underlined.



        RELWIDTH specifies the relative width of a character in relation
        to its height. This may of course only be used for mono-spaced
        fonts.  The value is interpreted as RELWIDTH/1000 of the font
        height.

        FONT-NAME is the name of the font within postscript.

        Instead of specifying RELWIDTH and FONT-NAME, LPU can fetch
        these (and other) information from a afm (adobe font metric)
        file; if the font has proportional spacing, this is mandatory.
        In this case, the name of the afm file (without path and
        extension) must be specified with a leading `@'. The afm file
        will be searched using the afm path (see below).


     %%AAffmmPPaatthh PPAATTHH--TTOO--AAFFMMFFIILLEE
        specifies the path to the directory, where the afm files are
        located.  Currently, only one absolute path may be given.



  The distribution contains a sample `lpu.dev' file with a configuration
  for the HP laser-jet 6l and a standard ghostscript installation under
  Linux.

  22..55..  TThhee PPAARR ffiillee

  this file contains some often used definitions for LPU programs.

  It is a pure text file, and the information is organized line by line.

  Empty lines, and lines which start with a `;' are ignored.

  Commands start with a dot, followed by a keyword and optional
  parameters.

  The following commands are allowed within PAR files:


     ..ddeeffiinnkk IIDD IINNKK--DDEEFFIINNIITTIIOONN

     ..ddeeffppeenn IIDD PPEENN--DDEEFFIINNIITTIIOONN

     ..ddeeffssttyyllee IIDD SSTTYYLLEE--DDEEFFIINNIITTIIOONN
        the syntax of these commands is identical to the LPU commands
        with the same names, and should be looked up there.

        The definitions within this file will be read by LPU before the
        first program instruction, so that every LPU program may rely on
        these definitions.


  22..66..  TThhee TTAABB ffiillee

  Basically, LPU works on forms and labels.  A form is a description of
  the structure of a whole page on the output device.  The form may
  contain one or more labels.  The labels on a form may all look exactly
  the same, or may be different.  Also, the position of the labels on
  the form may be very regular or totally chaotic.

  Known form types are combined in a single database file, the so-called
  TAB file.  This is a pure text file, which contains descriptions of
  forms and labels in a special syntax.

  Empty lines are ignored.

  Lines starting with `;' are comments and will be ignored too.

  A line starting with the keyword `form' begins a new form definition.
  After this keyword, a unique name for the form and a known paper
  format (as defined in the DEV file) are required.

  A `form' command is usually followed by one or more `label' commands.
  If no label command is given, the form is defined to consist of
  exactly one label, which takes the whole surface of the form and has
  the implicit name `label'.

  Every label on a form can be defined using the `label' command.

  A label command consists of the keyword `label', followed by a label
  name and the width and height of the label.  The label name must be
  unique within the form, and the width and height may be given as a DOT
  or UNIT value.

  After a label command, the sub commands `base', `xrep' and `yrep' are
  allowed.  If none of these subcommands is present, the label is
  assumed to be only once on the form, and is located in the top left
  corner (0,0) of the form.

  The subcommand `base' specifies the position of the defined label on
  the surface of the form.  The `base' command consists of the keyword
  `base', followed by the horizontal and vertical offsets of the label
  on the form, relative to the top left corner of the form.  Width and
  height may be given as DOT or UNIT values.

  If more than one identical label exists on the form (which may be the
  case with video cassette labels, visiting cards, etc.), this can be
  specified with the `xrep' and `yrep' commands, where `xrep' defines a
  repetition of the label in horizontal direction, and `yrep' does so in
  vertical direction.

  Both commands have the same structure: the keyword is followed by a
  count and an offset.  The count tells, how often the label exists on
  the form in the corresponding direction, and the offset (which may be
  given as a DOT or UNIT value) specifies the gap between two
  neighboring labels. A value of `0' means, that there is no gap between
  the labels.

  For all positions and offsets within forms, the top left corner has
  the coordinate (0,0).  Positive offsets point towards the right and
  bottom edges.

  33..  TThhee rreeffeerreennccee sseeccttiioonn

  33..11..  TThhee LLPPUU ccoommmmaannddss

  The contents of LPU command files are interpreted line by line.  The
  first character (respectively the first visible character) tells LPU
  which kind of information is contained:


    Empty lines will be ignored.

    Lines started with a `;' as first visible character are comments
     and will be ignored.

    Lines started with a `#', immediately followed by a keyword will be
     interpreted as preprocessor commands (see ``Preprocessor
     instructions'').

    All other lines started with a `#' are interpreted as comments and
     will be ignored.

     It is recommended, that such comments should always be written in
     the form `##', `#!' and so on to avoid misinterpretation, if the
     first word of the comment is written after the `#' without a space.

    Also, this definition allows a LPU file to start with a line like
     `#!/usr/bin/env lpu.sh', which can be used to run an LPU file as a
     command from within a Unix environment.

    Lines started with a colon in the first column are jump targets.
     These may be local program labels or entry points of procedures.

    Lines started with a dot are command lines.

    Lines started with a `"' in the first column are so called `quoted
     lines'.

  33..11..11..  JJuummpp ttaarrggeettss




     :::: PPRROOCC--NNAAMMEE
        defines the start (and name) of a new procedure. The procedure
        continues up to the begin of the next procedure or the end of
        the current source file.

        A procedure is called with the command `.do' and may be left at
        any time with the command `.return'.


     :: LLAABBEELL
        defines a label within a program. This label may be used as the
        target for a branch instruction.

        A label is always local to the procedure in which it is declared
        (the main program can be seen as a normal procedure with an
        implicit name).



  33..11..22..  TThhee ddoott ccoommmmaannddss

  The following dot commands are currently defined:



     ..bbaassee XXPPOOSS,, YYPPOOSS
        defines a new reference point on the current label.  By default,
        the reference point is (0,0), which is the top left corner of
        the label.

        The `.base' command moves the reference point horizontally by
        XPOS and vertically by YPOS DOT.


     ..bboorrddeerr TTOOPP,, BBOOTTTTOOMM,, LLEEFFTT,, RRIIGGHHTT
        defines margins for the current window.  The four values TOP,
        BOTTOM, LEFT and RIGHT set the values for the margins as DOT or
        UNIT values.


     ..cceenntteerr
        sets the default adjustment for text to `centered'.  This
        command only has an effect on quoted lines and the command
        `.text'.


     ..ccoonntt
        disables single step mode.


     ..ccrr
        positions the cursor to the leftmost position at the current
        vertical position. This is horizontal offset `0', or the amount
        of the left margin of the last `.border' command, whichever is
        greater.


     ..cctteexxtt ::SSTTRRIINNGG
        is identical to the command `.text', but the text is always
        centered.


     ..ddbb ......
        All commands that begin with `.db' are database commands.  These
        will be described in detail in the section ``database support''


     ..ddeebbuugg EEXXPPRR {{,, EEXXPPRR }}
        evaluates all given expressions and prints them in an implicit
        format to STDERR, dependent on the type of the expression.
        Finally, a newline is emitted.

        This command can be used to send messages to the user, or for
        debugging purposes.


     ..ddeeffiinnkk IINNKK--NNAAMMEE IINNKKDDEEFF
        defines a new color.

        INK-NAME is a unique name for the new color.  The format of
        INKDEF is:


          ( [cVALUE] [mVALUE] [yVALUE] [kVALUE] )


     where VALUE is a percentage between `0' and `100'.  `c', `m', `y'
     and `k' represent the color components `cyan', `magenta', `yellow'
     and `black'.

     Missing color components are counted with `0' percent.

     Alternatively, a predefined color may be specified in the form
     `@INK-NAME', where `INK-NAME' is the name of an already defined
     color.


     ..ddeeffppeenn PPEENN--NNAAMMEE PPEENNDDEEFF
        defines a new pen with the unique name PEN-NAME.  The format of
        PENDEF is:



            linewidth


     Alternatively, a predefined pen may be specified in the form `@PEN-
     NAME', where `PEN-NAME' is the name of an already defined pen.


     ..ddeeffssttyyllee SSTTYYLLEE--NNAAMMEE SSTTYYLLEEDDEEFF
        defines a new style with the unique name STYLE-NAME.  The format
        of STYLEDEF is:



            basename size { attr }




     where `basename' is the name of the font family, `size' is the font
     size in points, and `attr' is a list of any out of the following
     attribute flags:


       _N normal, no attributes specified

       _B bold

       _I italic

       _U underlined

        Alternatively, a predefined style may be specified in the form
        `@STYLE-NAME', where `STYLE-NAME' is the name of an already
        defined style.


     ..ddoo PPRROOCC--NNAAMMEE [[ PPAARRAAMM {{ ,, PPAARRAAMM }} ]]
        calls a procedure with the name `PROC-NAME'.

        After returning from this procedure, execution continues with
        the next instruction behind this command.  The return-code from
        the called procedure can be accessed afterwards by the system
        variable `$rc'.

        Optionally, any number of parameters may be specified behind the
        procedure name.  Within the called procedure, the system
        function `$parcnt' tells how many parameters were specified, and
        the system function `$param(PARNR)' can be used to access the
        parameter `PARNR' (where PARNR is in the range `1' to
        `$parcnt').

        `$param(0)' contains the name of the currently executing
        procedure.


     ..eejjeecctt
        flushes all pending output to the current form, ejects it (if it
        is a sheet of paper) and prepares a new form.

        The next `.label' commands starts on a new form.  By default,
        the same form type is used, but after the `.eject' and before
        the first `.label', a new form type may be selected if
        necessary, using the `.form' command.


     ..eeppss ......
        All commands that begin with `.eps' are related to eps file
        handling and will be described in detail in section ``Support
        for eps files''.
     ..eexxiitt MMEESSSSAAGGEE
        stops the execution of the program and leaves LPU.  The
        `MESSAGE' is printed to STDERR, and LPU's return-code is `9'.


     ..eexxiittiiff EEXXPPRR MMEESSSSAAGGEE
        evaluates the expression `EXPR' and stops the execution of the
        program and leaves LPU if the result is `true' (where `true' is
        any numerical value not equal to zero).

        The `MESSAGE' is printed to STDERR, and LPU's return-code is
        `9'.


     ..ffoorrmm IIDD
        selects the given form type.

        The `ID' must have been declared in the TAB-file within a `form'
        command.


     ..ffrraammee
        draws a thin frame around the current window.


     ..ggbbooxx [[@@((XXPPOOSS,, YYPPOOSS))]] WWIIDDTTHH,, HHEEIIGGHHTT [[..ffiillll]] [[..ppeenn PPEENNDDEEFF]] [[..iinnkk
        IINNKKDDEEFF]] [[..ddaasshheedd]] [[..ddootttteedd]]
        draws a rectangular box at the current cursor position (or at
        (XPOS, YPOS), if the `@' option is given), with a width of WIDTH
        and a height of HEIGHT DOT.

        The option `.pen PENDEF' selects a new pen type. Without this
        option, the current pen is used.

        The option `.ink INKDEF' selects a different drawing ink.

        The option `.fill' tells LPU to fill the box with the selected
        color and the selected fill pattern.

        The options `.dashed' and `.dotted' - or the combination of them
        - select one of the predefined line styles `solid' (which is the
        default), `dashed', `dotted' or `dashed dotted'.


     ..ggcciirrccllee [[@@ XX,, YY]] RRAADD [[..ffiillll]] [[..ppeenn PPEENNDDEEFF]] [[..iinnkk IINNKKDDEEFF]]
        draws a circle with the center at the current cursor position (
        or at (XPOS, YPOS), if the `@' option is given), and a radius
        RAD.

        The option `.pen PENDEF' selects a new pen type. Without this
        option, the current pen is used.

        The option `.ink INKDEF' selects a different drawing ink.

        The option `.fill' tells LPU to fill the circle with the
        selected color and the selected fill pattern.

        The options `.dashed' and `.dotted' - or the combination of them
        - select one of the predefined line styles `solid' (which is the
        default), `dashed', `dotted' or `dashed dotted'.


     ..gglliinnee [[@@((XXPPOOSS,, YYPPOOSS))]] XXOOFFFF,, YYOOFFFF [[..ppeenn PPEENNDDEEFF]] [[..iinnkk IINNKKDDEEFF]]
        [[..ddaasshheedd]] [[ddootttteedd]]
        draws a line with a relative endpoint (XOFF, YOFF) from the
        current cursor position (or from (XPOS, YPOS), if the `@' option
        is given).

        The option `.pen PENDEF' selects a new pen type. Without this
        option, the current pen is used.

        The option `.ink INKDEF' selects a different drawing ink.

        The options `.dashed' and `.dotted' - or the combination of them
        - select one of the predefined line styles `solid' (which is the
        default), `dashed', `dotted' or `dashed dotted'.


     ..ggoottoo LLAABBEELL
        unconditionally jumps to the given `LABEL'.  The label must be
        found within the context of the current procedure.


     ..hhlliinnee WWIIDDTTHH [[..ppeenn PPEENNDDEEFF]] [[..cceenntteerr || ..lleefftt || ..rriigghhtt]]
        draws a horizontal line at the current vertical position, with a
        length of `WIDTH', which is a DOT or UNIT value.

        The option `.pen PENDEF' selects a new pen type. Without this
        option, the current pen is used.

        The options `.left', `.right' and `.center' specify, where on
        the label the line will be drawn.


     ..hhoommee
        positions the cursor in the top left corner of the current
        window.  If a top or left margin is given, then the cursor is
        set to this offset, else to the value `0'.


     ..hhsskkiipp WWIIDDTTHH
        moves the cursor WIDTH DOTs to the right. The vertical position
        is not changed.  If WIDTH is negative, the cursor is moved
        abs(WIDTH) DOTs to the left.


     ..iiff EEXXPPRR SSTTAATTEEMMEENNTT
        evaluates the expression `EXPR', which has to be of type
        `integer'.

        If the result is `true' (any value not equal to zero), the
        command `STATEMENT' will be executed, else it will be ignored,
        and execution continues with the next instruction.

        At this time, only `goto', `do', `return ' and `exit' are
        allowed as a replacement for `STATEMENT'.


     ..iinnkk IINNKKDDEEFF
        selects a new color.  The format of INKDEF is defined at the
        `.defink' command.


     ..iinnppuutt [[##]]VVAARR--NNAAMMEE ::PPRROOMMPPTT
        prints the `PROMPT' to STDERR, then reads a line (terminated by
        ENTER) from stdin and assigns it to variable `VAR-NAME'.

        By default, the entered data is stored as a string, but if the
        `VAR-NAME' is preceded with a `#', the input is treated as a
        number.  If it is no valid number, then an error message is
        printed to STDERR, and the input must be repeated.

     ..llaabbeell [[IIDD || ==]]
        this selects the first (after a `.form' or `.eject' command) or
        next label on the current form.  If the parameter `ID' is given,
        the next label with this id is selected.  If `=' is given
        instead, the next label must be of the same type as the current
        label.

        If no labels of the requested type are left on the current form,
        the form is `ejected' and work continues on a new form.

        This command defines the whole surface of the selected label as
        the new output area.  No margins are set, and the cursor is
        positioned in the top left corner of the label.


     ..lleefftt
        sets the default adjustment for text to `left adjusted'.  This
        command only has an effect on quoted lines and the command
        `.text'.


     ..lleett VVAARR == EEXXPPRR
        evaluates the expression `EXPR' and assigns the result to the
        variable `VAR'.

        The variable must have been defined before.

        The type of the variable is set to the type of the result of the
        computed expression.


     ..lltteexxtt ::SSTTRRIINNGG
        is identical to the command `.text', but the text is always left
        adjusted.


     ..nnll [[NN]]
        positions the cursor at the beginning of the current line, and
        advances it afterwards `N' rows down.

        If `N' is omitted, `1' is assumed.

        The height of one character of the currently selected font is
        taken as the height of one row.


     ..nnooeejjeecctt
        this is identical to the `.eject' command, but the current sheet
        is not ejected. So the following drawing objects are placed `on
        top' of the old ones.


     ..ppeenn PPEENNDDEEFF
        selects a new pen.  The format of PENDEF is defined at the
        `.defpen' command.


     ..pprriinntt [[@@((XXPPOOSS,, YYPPOOSS))]] TTEEXXPPRR {{,, TTEEXXPPRR }}
        evaluates the text expressions `TEXPR' and prints them one by
        one starting from the current cursor position (or, if the `@'
        option is given, from position (XPOS, YPOS) ).

        If the `@' option is missing, then the cursor is advanced to the
        new position after that.


     ..rreeppeeaatt CCOOUUNNTT PPRROOCC--NNAAMMEE
        the procedure `PROC-NAME' is called `COUNT' times in sequence.

        During the first execution of the procedure, the system function
        `$count' reports `1', during the second execution, it reports
        `2', and so forth.


     ..rreeqquuiirreess VVEERRSSIIOONN
        requests a `minimum version' of LPU.  If the current version of
        LPU is below that number, the program will terminate with a
        corresponding error message.

        The version has to be specified in the form `V.R-S', where V is
        the version, R is the release and S is the sub-release.  An
        actual example would be `0.9-23' (without quotation marks).


     ..rreettuurrnn EEXXPPRR
        leaves the current procedure and returns control back to the
        calling procedure.

        The expression `EXPR' is evaluated and the result is returned to
        the calling procedure. There, the returned value may be accessed
        with the system function `$rc'.


     ..rriigghhtt
        sets the default adjustment for text to `right adjusted'.  This
        command only has an effect on quoted lines and the command
        `.text'.


     ..rrtteexxtt ::SSTTRRIINNGG
        is identical to the command `.text', but the text is always
        right adjusted.


     ..sseettxxyy XXPPOOSS,, YYPPOOSS
        moves the cursor position to a new location within the label.
        XPOS and YPOS are DOT or UNIT values.


     ..ssttoopp
        switches LPU to single step mode and invokes the runtime
        debugger.

        In this mode, before executing a command, the command and a
        prompt are printed on STDERR, and then the debugger waits for
        instructions, entered on STDIN.

        An empty input (only the `ENTER' key is pressed) executes the
        next lpu command.

        A detailed description of the behavior is given in the section
        ``The debugger''.


     ..ssttyyllee SSTTYYLLEEDDEEFF
        selects a new style.  The format of STYLEDEF is defined at the
        `.defstyle' command.


     ..tteexxtt ::SSTTRRIINNGG
        prints the `STRING' (all after the colon until the end of the
        line) at the current vertical cursor position.
        The default adjustment of the text is `centered', but this can
        be altered at any time using the commands `.left', `.right' and
        `.center'.

        The vertical position is not advanced by default.


     ..ttrrooffff
        this disables output of trace information.


     ..ttrroonn
        this enables output of trace information.

        In this mode, every command will be printed to STDERR before
        execution.


     ..uupprriinntt [[@@((XXPPOOSS,, YYPPOOSS))]] TTEEXXPPRR {{,, TTEEXXPPRR }}
        this is identical to the command `.print' except that all text
        is underlined.


     ..uussee DDBBNNUUMM PPRROOCC--NNAAMMEE
        the procedure `PROC-NAME' will be executed again and again,
        until the database file with the handle `DBNUM' reports an `end
        of file' condition.

        `DBNUM' is zero for the current database file, and greater zero
        for a dedicated database file.


     ..vvaarr IIDD {{,, IIDD }}
        this defines one or more variables.

        Variables must have been declared, before they may be used.

        A variable exists from the moment when it is defined, until the
        procedure where the variable was defined, is left.

        If a variable is accessed, LPU searches for the variable in the
        current procedure first, then in the parent procedure, then in
        the parent's parent procedure, and so forth.  Finally, the
        variable is searched in the main procedure.


     ..vvsskkiipp HHEEIIGGHHTT
        moves the cursor HEIGHT DOTs to the bottom. The horizontal
        position is not changed.  If HEIGHT is negative, the cursor is
        moved abs(HEIGHT) DOTs to the top.


     ..wwaattcchh EEXXPPRR {{,, EEXXPPRR }}
        Defines a list of expressions, which are `watched' during trace
        or single step mode.  When in one of these modes, the given
        EXPRessions are calculated and printed to STDERR before the next
        LPU command is executed.  This way, one can see what happens to
        variables while executing an LPU program.


     ..wwhhiillee EEXXPPRR ddoo PPRROOCC--NNAAMMEE
        evaluates the expression `EXPR' and executes the command
        `STATEMENT', if the result of `EXPR' is `true'.

        This will be repeated, until the result of `EXPR' becomes
        `false' for the first time; in this case, execution continues
        with the next command.

        If `EXPR' already evaluates to `false' at the first invocation,
        then `STATEMENT' is never executed.


     ..wwiinnddooww [[@@((XXPPOOSS,, YYPPOOSS)) [[ ..ffrraammee ]] WWIIDDTTHH,, HHEEIIGGHHTT]]
        defines a new output window within the current label.  When a
        new label is selected, a default window with the full size of
        the label is defined. The same happens when `.window' is called
        without any parameters.

        Otherwise, a window with the size WIDTH * HEIGHT is created at
        the current cursor position, or at position (XPOS, YPOS), the
        option `@(XPOS, YPOS)' is given.

        If the option `.frame' is given, a thin frame is drawn around
        the currently selected window.

        All coordinates are relative to the current window.

        The current settings may at any time be overwritten by a new
        `.window' command.

        After issuing the `.window' command, no margins are defined.
        Those may be defined (and altered again) later using the
        `.border' command.


  33..11..33..  QQuuootteedd lliinneess

  A quoted line is a line in a LPU command file, which contains a `"' in
  the first column.

  The line



           "LINE OF TEXT




  can be seen as a shorthand form of the two dot commands



           .text :LINE OF TEXT
           .nl




  The `LINE OF TEXT' (everything after the `"' until the end of the
  line) is printed at the current vertical position with the active line
  adjustment (centered, left or right adjustment).

  After that, the cursor is advanced to the beginning of the next line.

  Within the text, some replacements can be performed.  Details are
  explained in section ``text replacement''.





  33..11..44..  DDaattaabbaassee ssuuppppoorrtt

  LPU contains support for the import of structured text information
  from external files.  This can be used to create address labels and so
  forth, where a label is printed many times, but with different
  information on each of them.

  Currently, only a simple `text database' is supported.  Other database
  types are planned for future releases of LPU.

  Within LPU, this kind of `text database' is called a `TDB file', and
  the implied extension is `.tdb'.

  A TDB file is a pure text file, where each line of text represents a
  database record, and a special character is defined as a separator,
  which divides a text line into single database fields.

  By default, the separator is a null character, so that the whole line
  of text is seen as a single field. When opening a database file, a
  different separator can be defined.

  Currently, database support is implemented by these dot commands:


     ..ddbb ooppeenn [[##NN]] [[//TT]] DDBBNNAAMMEE
        opens an existing database file.  `DBNAME' is the name of the
        database file, and if the extension is missing, `.tdb' is
        assumed. Note that this may change in future releases, if other
        database types are supported.  The default type is `TDB'.

        More than one database file may be open at any time, and a
        `handle' is assigned to every open database file. The handle is
        a small positive integer with values starting from `1'. The
        special handle `0' accesses the `current' database file.

        If the option `#N' is given, the database file is assigned to
        handle `N', else LPU uses a free handle. This handle will become
        the new `current' handle.  Also, the first record of the
        database file will become the `current record'.

        If the option `/T' is given, the character `T' will become the
        new field separator for that database file.  Without this
        option, there will only be one field in every record, which
        contains the whole line of text.  Any printable character can be
        used for `T'.


     ..ddbb cclloossee
        closes the open database file with the current handle.


     ..ddbb uussee ##NN
        defines handle `N' as the new current handle and makes the open
        database file with this handle to the new current database file.


     ..ddbb ttoopp
        positions the `record pointer' to the first record of the
        current database file.


     ..ddbb nneexxtt
        positions the `record pointer' to the next record within the
        current database file.


     ..ddbb ffiinndd NN PPAATTTTEERRNN
        searches the current database file, beginning with the current
        record, for a record with the value `PATTERN' in field `N' of
        the record.  Field numbers start with `1'.

        If a record was found, then this will become the new current
        record, else an `end of data' condition will occur. In this
        case, the record pointer points to a position `behind the last
        record' of the database file.

  The state and current values of the database may be accessed by a
  couple of functions (see ``System functions''); most of them begin
  with `$db'.

  33..11..55..  SSuuppppoorrtt ffoorr EEPPSS ffiilleess

  Starting with version 0.9-23, LPU contains experimental support for
  `embedded postscript' files (eps).

  The contents of an eps file is always shown as a `black box'; only the
  size and the position on the current label may be changed.

  There is a simple way to show the contents of a eps file with one
  command (eps insert), where you supply position and size to the
  command as parameters, and a complex way where you can open the file
  (eps open), access file attributes ($eps{ATTR}), resize (eps resize)
  or rescale (eps rescale) and show (eps show) the file contents. You
  can repeat this process as often as you like.  When you don't need the
  file any more, you can close it (eps close).

  The second form is more complicated, but also more flexible.

  As it was stated above, the eps support is experimental only, and the
  command syntax may still change.

  Here is a description of the available eps commands in LPU:



     ..eeppss iinnsseerrtt FFIILLEENNAAMMEE {{ OOPPTTIIOONN }}
        this command prints the contents of an eps file on the current
        label.

        FILENAME is the name of the eps file in Unix notation; the file
        extension must be given.

        Without any options, the file will be printed at the current
        cursor position in its original size.

        The following options are supported:


       _@_(_X_P_O_S_,_Y_P_O_S_)

        defines the position on the label, where the file contents will
        be printed.  XPOS and YPOS are DOT values.

       _._s_i_z_e_(_X_S_I_Z_E_,_Y_S_I_Z_E_)

        defines the size of the printed object.  XSIZE and YSIZE are DOT
        values.

       _._s_c_a_l_e_(_X_S_C_A_L_E_,_Y_S_C_A_L_E_)

        the eps object is scaled by XSCALE and YSCALE in the
        corresponding directions.
       _._f_u_l_l

        scales the eps object, so that it fills the current output
        window completely.

       _._h_c_e_n_t_e_r

        tells LPU to use the middle of the eps object to position it
        horizontally. Without this option, the left margin will be taken
        as the reference point.

       _._v_c_e_n_t_e_r

        tells LPU to use the middle of the eps object to position it
        vertically. Without this option, the top margin will be taken as
        the reference point.

       _._c_e_n_t_e_r

        this is a combination of `.vcenter' and `.hcenter'.

       _._h_s_k_i_p

        tells LPU to move the cursor horizontally for exactly the width
        of the eps object after printing it.  Without this option, the
        cursor is not moved.

       _._v_s_k_i_p

        tells LPU to move the cursor vertically for exactly the height
        of the eps object after printing it.  Without this option, the
        cursor is not moved.


     ..eeppss ooppeenn FFIILLEENNAAMMEE
        this command opens the eps file and makes it available to the
        other eps functions and commands.

        FILENAME is the name of the eps file in Unix notation; the file
        extension must be given.

        After opening the file, other eps commands may be used, until
        the file is closed again, using the `eps close' command.  Only
        one eps file may be open at any time.

        While the file is open, the system function `$eps{ATTR}' may be
        used to gather information about the eps file. This will be
        described in detail in the `system functions' section.


     ..eeppss rreessiizzee XXSSIIZZEE,, YYSSIIZZEE
        this changes the size of the eps object in the currently open
        file.  XSIZE and YSIZE specify the new size in DOTs.


     ..eeppss rreessccaallee XXSSCCAALLEE,, YYSSCCAALLEE
        this is another way to change the size of the eps object.
        XSCALE and YSCALE are float values with give the scaling factor
        for the new size in relation to the original size.  `1.0' for
        both values keep the original size, while '2.0' doubles the size
        in the corresponding direction.

        The scaling factor always corresponds to the original size of
        the eps file. So, only the last `eps rescale' or `eps resize'
        has an effect on a following print command.

     ..eeppss sshhooww {{ OOPPTTIIOONN }}
        this commands prints the eps object once with the current size,
        as defined by the last `eps resize' or `eps rescale' (or the
        original size, if none of these commands was used after the last
        `eps open'). It can be called as often as required.

        If no option is given, the object is printed at the current
        cursor position with the top left corner of the object as the
        reference point.

        The position can be changed with the '@' option, and the
        reference point is modified by the options `.hcenter',
        `.vcenter' and `.center'.

        Here is a list of the available options:


       _@_(_X_P_O_S_,_Y_P_O_S_)

        defines the position on the label, where the file contents will
        be printed.  XPOS and YPOS are DOT values.

       _._s_i_z_e_(_X_S_I_Z_E_,_Y_S_I_Z_E_)

        defines the size of the printed object.  XSIZE and YSIZE are DOT
        values.

       _._h_c_e_n_t_e_r

        tells LPU to use the middle of the eps object to position it
        horizontally. Without this option, the left margin will be taken
        as the reference point.

       _._v_c_e_n_t_e_r

        tells LPU to use the middle of the eps object to position it
        vertically. Without this option, the top margin will be taken as
        the reference point.

       _._c_e_n_t_e_r

        this is a combination of `.vcenter' and `.hcenter'.

       _._h_s_k_i_p

        tells LPU to move the cursor horizontally for exactly the width
        of the eps object after printing it.  Without this option, the
        cursor is not moved.

       _._v_s_k_i_p

        tells LPU to move the cursor vertically for exactly the height
        of the eps object after printing it.  Without this option, the
        cursor is not moved.


     ..eeppss cclloossee
        this command closes an open eps file. After that, a new eps file
        may be used.


  33..11..66..  PPrreepprroocceessssoorr iinnssttrruuccttiioonnss

  Lines beginning with a `#', immediately followed by a keyword are
  preprocessor instructions.  They are evaluated and executed when
  reading the source-code.
  The following preprocessor instructions are available at this time:


     ##iinncclluuddee FFIILLEENNAAMMEE[[..EEXXTT]]
        reads and inserts the file `FILENAME' at the current position
        into the source code of the LPU program.  If no extension is
        given, `.lpi' is appended to the filename.


  33..22..  TTeexxtt rreeppllaacceemmeenntt

  Before a line of text is processed, the replacement of special symbols
  takes place.

  These replacement symbols start with a backslash. The symbol will be
  replaced by the current value of the evaluated symbol.

  The following replacement symbols are defined:


     ``\\\\''
        is replaced by a single backslash.


     ``\\00''
        is replaced by the name of the current procedure.


     ``\\NN'',, wwiitthh NN==``11''....``99''
        is replaced by parameter `N' of the current procedure.


     ``\\##''
        is replaced by the number of parameters.


     ``\\??''
        is replaced by the return code of the last executed procedure.


     ``\\@@NN'',, wwiitthh NN==``00''....``99''
        is replaced by the field number `N' of the current record of the
        current database file.


     ``\\@@##''
        is replaced by the number of fields in the current database
        record.


     ``\\@@$$''
        is replaced by the current record number of the current database
        file.


     ``\\@@??''
        is replaced by the `end of data' state (`0' or `1') of the
        current database file.


     ``\\((IIDD))''
        is replaced by the contents of the variable `ID'.


     ``\\{{EEXXPPRR}}''
        is replaced by the result of the evaluated expression `EXPR'.
     ``\\[[EENNVV]]''
        is replaced by the contents of the environment variable `ENV'.

  33..33..  EEvvaalluuaattiinngg eexxpprreessssiioonnss

  Many times within this document, an expression can be specified.  Here
  is an explanation of how expressions are constructed.

  An expression contains operands and operators.

  Operands may be numerical values, string values, variables, and system
  functions.

  They are tied together by numerical, logical and comparison operators.

  If an expression is evaluated, it results in a type and a value of
  that type.  The result types of an expression can be:



     TT__SSTTRR ((ssttrriinngg))
        this is an array of characters.


     TT__NNUUMM ((iinntteeggeerr vvaalluuee))
        this is an integer value (32 bit int on most systems)


     TT__FFLLTT ((ffllooaattiinngg ppooiinntt vvaalluuee))
        this is a floating point value (64 bit double on most systems)


  Sometimes, one of the following expression types is required:



     nnoorrmmaall eexxpprreessssiioonn
        is an expression of _a_n_y type.


     tteexxtt eexxpprreessssiioonn
        requires a result type of T_STR.


     nnuummeerriiccaall eexxpprreessssiioonn
        requires a result type of T_NUM or T_FLT


     llooggiiccaall eexxpprreessssiioonn
        requires a result type of T_NUM.  The value `0' is defined as
        `false', and all other values are defined as `true'.



  Here is a list of all currently defined operators, grouped by classes
  (you will see that most of them are equivalent to `C' operators):



     ccoommppaarriissoonn ooppeerraattoorrss
        `=', `<>', `<', `<=', `>', `>='


     nnuummeerriiccaall ooppeerraattoorrss
        `+', `-', `*', `/', `%'

     llooggiiccaall ooppeerraattoorrss
        `&', `|', `&&', `||', `!'


     ootthheerr ooppeerraattoorrss
        `#' converts the following factor into a numerical value, if
        this is possible.




  The following system functions are currently avaliable:



     $$bbaasseelliinnee
        returns the distance between the baseline and the top edge of
        the bounding box of the currently selected font, measured in
        DOTs.


     $$bbaattcchhmmooddee
        returns `1', if LPU is currently running in batch mode, `0'
        otherwise.


     $$ccoonnccaatt((SSTTRRIINNGG,, SSTTRRIINNGG {{,, SSTTRRIINNGG}}))
        concatenates two or more strings to one longer string.


     $$ccoouunntt
        this is a loop counter within `.repeat' statements.  Outside of
        `.repeat' statements, it usually returns `1'.


     $$ddbbfflldd((DDBB,, FFLLDD))
        returns the contents of field `FLD' of the current record of
        database file `DB'.


     $$ddbbffllddss((DDBB))
        returns the number of fields in the current record of database
        file `DB'.


     $$ddoottss((EEXXPPRR))
        evaluates a `unit' type expression and returns the result,
        converted to the unit DOT.

        `EXPR' may be of type T_NUM or T_FLOAT, immediately followed by
        a unit id.  The result will always be of type T_NUM.


     $$eeoodd((DDBB))
        returns `1', if the `end of data' is reached for the database
        file `DB', and `0' otherwise.


     $$eeppss{{AATTTTRR}}
        returns an attribute of the currently opened eps file.

        The following attributes can be used:


       _x_s_i_z_e

        returns the original width of the eps file (derived from the
        bounding box) in the unit DOT.

       _y_s_i_z_e

        returns the original height of the eps file (derived from the
        bounding box) in the unit DOT.


     $$ffllooaatt((EEXXPPRR))
        evaluates the expression `EXPR' and converts the result to the
        type T_FLT.


     $$ffoonntthheeiigghhtt
        returns the height of the currently selected font, measured in
        DOTs.


     $$ffoorrmmccnntt
        returns the number of form types, that are defined in the TAB
        database.


     $$ffoorrmmiidd((FFNNRR))
        returns the name of form number `FNR' in the TAB database.

        `FNR' can be in the range `0' .. `$formcnt-1'.  The special
        value `.' returns the name of the currently selected form.


     $$ggeennddaattee
        returns the date of the generation of the currently running LPU
        image as a string value.


     $$iissnnuumm((VVAARR))
        checks, if a variable with name `VAR' exists and has a numerical
        type.  Returns `1' if true and `0' otherwise.


     $$iissssttrr((VVAARR))
        checks, if a variable with name `VAR' exists and has a textual
        type.  Returns `1' if true and `0' otherwise.


     $$iissvvaarr((VVAARR))
        checks, if a variable with name `VAR' exists.  Returns `1' if
        true and `0' otherwise.


     $$llbbllccnntt((FFNNRR))
        returns the number of different label types, which are defined
        with form number `FNR'.

        For a description of `FNR', see the function `$formid'.


     $$llbblliidd((FFNNRR,, LLNNRR))
        returns the name of the label type with index `LNR' in the form
        `FNR'.

        For a description of `FNR', see the function `$formid'.

        `LNR' can be in the range `0' .. `$lblcnt(FNR)-1'.  The special
        value `.' returns the name of the currently selected label type.
     $$llbbllxxccnntt((FFNNRR,, LLNNRR))
        returns the number of identical labels of type `LNR' in form
        `FNR', which are positioned in horizontal order.

        For a description of `FNR', see the function `$formid'.  For a
        description of `LNR', see the function `$lblid'.


     $$llbbllyyccnntt((FFNNRR,, LLNNRR))
        returns the number of identical labels of type `LNR' in form
        `FNR', which are positioned in vertical order.

        For a description of `FNR', see the function `$formid'.  For a
        description of `LNR', see the function `$lblid'.


     $$llttrriimm((SSTTRR))
        returns the string value `STR', with all leading blanks removed.


     $$nnooww
        returns the current time as `ansi time' (the number of seconds
        since Jan, 1st 1970, 00:00 GMT) of type T_NUM.


     $$oodddd((EEXXPPRR))
        evaluates the expression `EXPR' (which must be of type T_NUM),
        and returns `1', if the result is odd, `0' otherwise.


     $$ppaarraamm((NN))
        returns the value of parameter `N' of the current procedure.
        Parameter numbers range from `1' to '$parcnt', while parameter
        `0' returns the name of the current procedure.


     $$ppaarrccnntt
        returns the number of parameters, that were passed to the
        current procedure.


     $$rrcc
        returns the exit state of the last procedure that was called
        from the current procedure.


     $$rrttrriimm((SSTTRR))
        returns the string value `STR', with all trailing blanks
        removed.


     $$ssttrr((VVAALL,, LLEENN [[,, DDEECC]]))
        converts the numerical value `VAL' to a string representation
        with a minimum width of `LEN' digits.  If the parameter `DEC' is
        specified, and greater than zero, then the string represents a
        fixed point number with `DEC' digits behind the decimal point.


     $$ssttrrffttiimmee((TTIIMMEE,, FFOORRMMAATT))
        creates a string with a time format.

        The parameter `TIME' must be of type T_NUM, and is interpreted
        as an `ansi time' value.

        The parameter `FORMAT' contains a format specification, which is
        identical to the format string of the `C' function `strftime'.
     $$ssttrrlleenn((SSTTRRIINNGG))
        returns the number of characters in the T_STR type expression
        `STRING'.


     $$ssttrrppaadd((SSTTRRIINNGG,, PPAATT,, LLEENN))
        returns a string which is constructed by appending the string
        expression `PAT' repeatedly to the string expression `STRING',
        until the length `LEN' is reached.  If the resulting string is
        too long, it is truncated to the length `LEN'.


     $$ssttrrrreepp((SSTTRRIINNGG,, CCOOUUNNTT))
        returns a string, which is constructed by concatenating the
        string expression `STRING' `COUNT' times.


     $$ssttrrsseegg((SSTTRRIINNGG,, PPOOSS,, LLEENN))
        returns a segment of the string expression `STRING', starting at
        offset `POS' (starting with `0') with a length of `LEN'
        characters.

        If `LEN' is negative, then the last `abs(LEN)' characters are
        extracted from the string, but not starting before offset `POS'
        of the string.


     $$ssttrrssttrr((SSTTRRIINNGG,, PPAATT))
        returns the offset, where the substring `PAT' appears the first
        time within the string `STRING'; the offset starts with `0'.  If
        `PAT' doesn't appear within `STRING', the function returns `-1'.


     $$ssttrrttookk(([[SSTTRR,,]] LLIIMM))
        returns the first or next token of string `STR'.  The first
        time, the function must be called in the form



              $strtok(STR, LIM)





     In this case, a copy of 'STR' is stored internally, and the first
     part of the string, up to the first occurrence of any of the
     characters from within string `LIM' is returned.

     All following calls to this function should have the form



              $strtok(LIM).





     This will return the next part of the internally stored string, up
     to the first occurrence of any of the characters from within string
     `LIM'.

     This will continue until the stored string is empty.  After that,
     all subsequent calls to this function in the second form will
     return an empty string.
     $$ssttrrwwiidd((SSTTRR))
        returns the width of the given string expression `STR' for the
        current font, measured in DOTs.


     $$ttrriimm((SSTTRR))
        returns the string value `STR', with all leading and trailing
        blanks removed.


     $$vveerrssiioonn
        returns the current version of LPU as a string in the form `X.Y-
        Z'.


     $$xxbbaassee
        returns the horizontal offset of the current window within the
        current label in DOT.


     $$xxppooss
        returns the horizontal position of the cursor within the current
        window in DOT.


     $$xxssiizzee
        returns the width of the current window in DOT.


     $$yybbaassee
        returns the vertical offset of the current window within the
        current label in DOT.


     $$yyppooss
        returns the vertical position of the cursor within the current
        window in DOT.


     $$yyssiizzee
        returns the height of the current window in DOT.


  44..  OOtthheerr ffeeaattuurreess

  44..11..  TThhee ddeebbuuggggeerr

  Starting with version 0.9-15, a small debugger is integrated in LPU.

  The debugger can be invoked at any time within a LPU program by
  inserting the command `.stop', which turns LPU into `single step
  mode'.  And - starting with version 0.9-23 - pressing `CTRL-C' while a
  LPU program is running, will invoke the debugger, too.

  In this mode, the next instruction and a prompt are printed to STDERR
  before the instruction is executed.  The debugger then waits for input
  from STDIN, terminated by the ENTER key.  It then evaluates the input
  and executes the corresponding command.

  The following debugger instructions are defined:


     ??  A list of all available debugger commands is printed.



     aa VVAARR == EEXXPPRR
        evaluates the expression `EXPR' and stores the result into
        variable `VAR'.


     cc  prints the calling stack of all procedures.


     ee EEXXPPRR
        evaluates the expression `EXPR' and prints the result to STDERR.


     gg  Go. The single step mode is disabled, and the execution of the
        LPU program is resumed with the current instruction.  This
        leaves the debugger and returns control back to the runtime
        system.


     qq  Quit. Stops execution of the program and leaves LPU.


     ww EEXXPPRR {{,, EEXXPPRR }}
        Defines a list of EXPRessions, which shall be `watched'.  For
        more details, see the LPU command `.watch'.


     EENNTTEERR
        An empty input (only the ENTER key), executes the next
        instruction of the program, and then comes back to the debugger
        before the following instruction.

  The LPU command `.cont' disables the `single step mode', so that
  executing this instruction within the debugger is equivalent to the
  debugger instruction `g'.

  44..22..  TTrraacciinngg

  The debugger, which was described in the last section, is very helpful
  if you want to analyze what is going on in a special code section, but
  it is very boring if you must walk step by step through a very long
  program until you come to the section, where the error occurs.

  This is where tracing comes in.  The trace mode is enabled with the
  command `.tron' and disabled with the command `.troff'.

  When trace mode is active, every LPU instruction is printed to STDERR,
  before it is executed. This should lead fast to the point where the
  error occurs.  Now, you can place a `.stop' command at the beginning
  of the offending section of code and inspect what is going on with the
  debugger.

  The command `.debug' is very useful in this respect; details are
  described in the section on dot commands.

  55..  CClloossiinngg rreemmaarrkkss

  LPU is currently under development.  Many details may change in future
  releases.

  Therefore, the program should be used with caution.  Also, there may
  be notable differences between the documentation and the behavior of
  the software.

  Comments, Suggestions, bug reports and all other kinds of feedback are
  welcome.

  Please send your remarks to



           John R. Schrader
           jrschrader@mainz-online.de




























































