COMMENT(
        Leave a definition of a label empty if not used. E.g.,
        if you don't have other programs related to this one,
        use: 
        SUBST(@SEEALSO) ()

        Use bf() for items that should appear literally in commands, etc.
        use em() for formal names, that should be replaced by actual values
            in real life.
)
SUBST(@SECTION)         (1)

SUBST(@DATE)            (Nov. 1999)
SUBST(@AUTHOR)          (Frank B. Brokken (bf(frank@icce.rug.nl)).)
SUBST(@ORGANIZATION)    (ICCE, University of Groningen.)

SUBST(@PROGRAM)         (icmake)
SUBST(@PROJECT)         (icmake)
SUBST(@DISTRIBUTION)    (icmake-X.YY.tar.gz)

SUBST(@SHORTDESC)       (an alternative to em(make))
SUBST(@SYNOPSYS)(
       @PROGRAM [flags] source[.im] [dest[.bim]] [-- [args]]
)
SUBST(@OPTIONS)(
    startit()
    it() flags:  optional flags:
        startit()
          it()tt(-a): information about ICMAKE
          it()tt(-b): blunt execution of the destinationfile
          it()tt(-c): the destination file is compiled
          it()tt(-i file): 'file': name of source, end of icmake arguments
          it()tt(-o file): all icmake output is redirected to `file' (Not
                        implemented on unix platforms)   
          it()tt(-p): only the preprocessor is activated
          it()tt(-q): quiet mode: copyright banner not displayed
          it()tt(-t file): 'file' is used as a temporary bim-file, to be
                        removed on exit. Argument processing stops.
        endit()
   it()tt(source): make description source file (default extension: .im)
   it()tt(dest):   binary make file             (default:    source.bim)
   it()tt(--):   optional icmake-file arguments separator
   it()tt(args):  optional arguments following -- received by
                             the icmake file in its argv-list
   endit()    
    With em(icmun):nl()
    em (icmun bimfile)
    startit()
    it() bimfile: file to unassemble
    endit()

)
SUBST(@DESCRIPTION)(
        em(icmake) is a program that can be used as an alternative to
em(make). em(Icmake) is a shell program, normally calling the following
programs:
    startit()
        it()tt(icm-pp)    to preprocess the icmake file 
        it()tt(icm-comp)   to compile the icmake file to byte-code
        it()tt(icm-exec)   to interpret the byte-code file
    endit()
    The program tt(icmun) may be used to disassemble the compiled 
byte-code file.

    startit()
    it()tt(Syntax elements of the icmake file):

    it() Preprocessor directives:
    verb(
    // comment              : comment until end-of-line
    /* comment */           : comment between /* and */
    #include "filename"     : includes a file
    #include <filename>     : includes a file from directory
                              pointed to by IM variable
    #define ident redef     : defines ident to expand to redef
    #! ...                  : ignored line
    )
    Note: 

    startit()
        it() Any character on a line beyond an tt(#include ...) directive
              is ignored.
        it() Comment in a tt(#define) is removed, but must given be on 
            one line.
        it() tt(#!) may be used on unix platforms to use icmake-shell
                  scripts, in combination with the -i or -t flags.

              E.g., if the first line of an (executable) icmakefile 'icm'
                  (without extension) contains
        centt(#! /usr/bin/icmake -qi)
           then 'icm' may be given as a command, thus executing
        centt(/usr/bin/icmake -qi icm ...)
                  Alternatively, 
        centt(#! /usr/bin/icmake -qt /tmp/icm)
                  can be used, executing
        centt(#! /usr/bin/icmake -qt /tmp/icm icm ...)
                  In this case the binary makefile is not kept, but a
                  temporary file tt(/tmp/icm.PID)
        is used and removed on exit. The
                  PID extension being the process-id of the icmake program
                  executing icm.
    endit()

    it() Types and variables:
    verb(
int             (-0x8000..0x7fff or 'x', x: ASCII character)
string          (a piece of text)
list            (a number of strings)
void            (may be used for user-defined functions)
    )
        Global and local variables are supported, as well as arguments
        to user-defined functions.
    it() Escape sequences in strings:
    verb(
\a \b \f \n \r \t
    )
    Other escape-sequences tt(CHAR(92)x) is interpreted as a literal tt(x) 
    (e.g., use tt(CHAR(92)CHAR(92)) for tt(CHAR(92))). 
    it() Flow control statements:
    verb(
    if (condition) statement
    if (condition) statement else statement
    for (init; condition; increment) statement 
    return (expression) - no (expression) with void functions
    break
    exit (expression)
    )    
    With the tt(for) statement, init, condition and increment are optional.
    With tt(void) functions, the tt(return) statement must not have a trailing
expression. In those cases use tt(return;)
    it() The user-defined function main():

                Arguments may be (int argc, list argv, list envp)
                or a subset of those, similar to C.

                Argc is the number of elements in argv.

                Argv holds the arguments, with element 0 the .bim filename,
                element 1 the first argument etc.

                Envp holds the environment, element 0 is the first variable,
                element 1 its value, element 2 the second variable,
                element 3 its value, etc.
    it() Operators:

                The ternary C-operator  ?:  is not supported.

                All other arithmetic operators of C are supported, operating
                on int-operands.

                Operators available for string-operands:
        verb(
a + b           concatenates b to a
+=              concatenation and assignment
== != <= >= < > equality testing
!a              empty string test
a younger b     true if file a is more recent
a older b       true if file b is more recent
a newer b       synonym for younger
        )
                    Note: Equality testing is also alphabetically, using the
                          ordering of the ASCII-set. Internally tt(strcmp())
                          is
                          used to compare strings.

                Operators available for list-operands:
        verb(
a + b           merging of lists
a - b           opposite
+= -=           merging/subtraction and assignment
== !=           equality testing
!a              empty list test
        )

                Typecasts:

                        Strings may be cast to ints and vice versa. 
                        Strings may be cast to lists.

    it() Predefined symbols:
    verb(
--------------------------------------------------------------
symbol          1 when defined on the platform ... otherwise 0
--------------------------------------------------------------
MSDOS           MS-DOS platform (with MSC 7.00 compiler)
unix            Unix, usually with GNU's gcc compiler
linux           '386 or '486 running Linux (usually with gcc)
M_SYSV, M_UNIX  '386 or '486 running SCO/Unix (usually with
Microsoft C)
_POSIX_SOURCE   Unix with Posix complient compiler
__hpux          HP-UX, with the native HP compiler
--------------------------------------------------------------
    )
    it() Predefined constants:    
    verb(
Used with makelist():
---------------------
O_ALL       8           O_FILE      1           O_DIR       2
O_SUBDIR    4

Used with echo():
-----------------
OFF         0           ON          1

Used with execute() and system() etc.:
--------------------------------------
P_CHECK     0           P_NOCHECK   1

Used with stat():
-----------------
S_IFCHR     1           S_IFDIR     2           S_IFREG     4
S_IREAD     8           S_IWRITE   16           S_IEXEC    32
    )
    it() Predefined functions:
        Note: In parameterlists below, the notation [type = value,] indicates
              a default function argument of the indicated type and value.
              An argument of the indicated type may be prvided to overrule the
              default.
    verb(
arghead (string h)
        defines argument head, to be used with execute ()
argtail (string t)
        defines argument tail, to be used with execute ()
int ascii (string s)
        returns first character of 's' as an int; e.g.,
        ascii ("A") gives 65
string ascii (int i)
        returns i as a string, e.g., ascii (65) gives "A"
string change_base (string file, string newbase)
        changes basename of file, returns changed name
string change_ext (string file, string newext)
        changes extension of file, returns changed name
string change_path (string file, string newpath)
        changes path specification of file, returns changed name
string chdir ([int = P_CHECK,] string newdir)
        changes directory, returns the previous dir.
        Use "." for newdir to get current working directory.
        Use ""  for newdir to get startup working directory.
cmdhead (string h)
        defines command head, to be used with execute ()
cmdtail (string t)
        defines command tail, to be used with execute ()
echo (int opt)
        sets re-echoing of called programs, OFF for no echo 
        (default: ON)
string element (int index, list lst)
        returns index-th string from list
string element (int index, string str)
        returns index-th character from string as a mini-string
exec ([int = P_CHECK,] string cmd, ...)
        runs command with arguments.
execute ([int = P_CHECK,] string cmd, string cmdhd, 
            string arghd, ..., string argtl, string cmdtl)
        same as exec(), except for command head/tail and argument
        head/tail. The actual executed program will start with the
        cmd, followed by the cmdhd. Next is a series of arguments,
        all enclosed by arghd and argtl. The command terminates 
        with cmdtl.
int exists (string file)
        returns non-zero if file exists
list fgets (string file, int offset)
        reads next string from file at offset. Return value:
        element(0,retlist) is the read string (including CHAR(92)n),
        element(1,retlist) is the next offset to read.
        An empty return list signifies EOF.
fprintf (string file, ...)
        same as printf, but appends to file
string get_base (string file)
        returns basename of file
string get_ext (string file)
        returns extension of file
string getch ()
        returns keypress as mini-string
string get_path (string file)
        returns path of file
int getpid ()
        returns process-id (UNIX) or PSP-paragraph (DOS) of
        icm-exec
string gets ()
        returns string read from keyboard
list makelist ([int = O_FILE,] string mask)
        returns list of all files matching mask
        Use:
            O_ALL     to obtain all directory entries,
            O_DIR     to obtain a list of (sub)directories,
            O_FILE    (default) to obtain a list of only files,
            O_SUBDIR  to obtain a list of only subdirectories.
list makelist ([int = O_FILE,] string mask, newer, 
                string comparefile)
        returns list of all files matching mask which are newer
        than the comparefile. Operator younger is synonymous to
        newer.
list makelist ([int = O_FILE,] string mask, older, 
                string comparefile)
        see above; returns list of files older than the 
        comparefile.
list makelist ([int = O_FILE,] string mask, newer, 
                string comparefile)
    returns list of all files matching mask which are newer than
    the comparefile. Operator younger is synonymous to newer.
list makelist ([int = O_FILE,] string mask, older, string comparefile)
        see above; returns list of files which are older than the
        comparefile.
printf (...)
        prints arguments to screen
putenv (string)
        adds string to environment (as long as icmake is running).
        Use format: "VAR=value".
int sizeof (list l), int sizeoflist (list l)
        returns number of strings in list
list stat ([int = P_CHECK,] string entry)
        returns 'stat' information of directory entry 'entry' as 
        a list. The following list-elements are defined:
            Element             Definition
            --------------------------------------
                0               attribute value
                1               size of the file
            --------------------------------------
        Attributes are  returned as bit-flags, composed from the
        following predefined constants:
            -----------------------------------------------------
            S_IFCHR     1       S_IFDIR     2       S_IFREG     4
            S_IREAD     8       S_IWRITE   16       S_IEXEC    32
            -----------------------------------------------------
int strlen (string s)
        returns number of characters in s 
        (as C's strlen() function)
string strlwr (string s)
        returns lower-case duplicate of s
string strupr (string s)
        returns upper-case duplicate of s
list strtok (string str, string separators)
        returns list holding substrings of cut-up string
int substr (string big, string small)
        returns index in big where small occurs, or -1 if small 
        does not occur in big
int system ([int = P_CHECK,] string command)
        runs command. Return value indicates exit status.
    )
)
SUBST(@FILES)(-)

SUBST(@SEEALSO)(bf(make(1)))

SUBST(@DIAGNOSTICS)(-)

SUBST(@BUGS)            (No Documented Bugs.)
SUBST(@COPYRIGHT)(
    This is free software, distributed under the terms of the GNU General
    Public License.
)
COMMENT(Do not modify from here)
INCLUDEFILE(/usr/local/manpages/executables.1/pagedef.yo)