Contents

Using HIP

Normal Mode

HIP   options   filename ...

Multiple file names may be specified, and each will be processed in turn. The filename is relative to the current directory for the process, or a directory specified in the HIPINC environment variable, and may contain full or relative path information. Each file specified on the command line is rewritten in place if any HIP commands in the file were processed.

Included files may contain additional HIP commands. Includes are expanded as encountered and may nest to several levels. Note that only the HIP commands occurring in the top level document will be visible in the expanded document. Also, any existing expansion within nested documents is ignored, and a fresh expansion is done each time. To put that another way, running HIP explicitly on a document which is only to be included in another document won't really do much but make it bigger (unless it contains replace commands.)

Valid options are:

• -b switches to Build Mode (described below)
• -s silent, suppresses all informational messages
• -u unHIP, removes HIP expansions (see below)

If all goes well, the output of HIP shows the dependency chain of each processed file in the style of typical 'make' line, like this:

filename : inc1 inc2

This output can be suppressed with the -s option. Error messages may also appear in the output.

Build Mode

HIP   options   -b output_file source_file

Build mode generates a separate output file from a source file, instead of the in-place rewrite of normal mode. Only one source file may be processed in each HIP invocation in this mode. The output file will not contain the HIP commands themselves from the source file, only the expansions thereof.

The only valid option in build mode is -s for silent operation.

HIPINC Environment Variable

The HIPINC environment variable may be used to establish a search path for files HIP accesses in include, replace and table commands. Multiple directories may be specified, each separated by ';'. The actual mechanics of setting an environment variable depend on the system on which HIP is running, but usually take the form of a shell command such as:

set HIPINC=pathspec1;pathspec2;

or

setenv HIPINC="pathspec1;pathspec2;"

To find a file specified in an include command, HIP will look relative to the current directory for the process first, and then, if not found, each path specification in 'HIPINC', if defined, will be prepended to 'filename', and HIP will attempt to open a file by that name. Note that no separator character is added, hence a shell command such as:

set HIPINC=D:/includes

<!--HIP inc file.txt -->

D:/includesfile.txt

A special note on UnHIPping

HIP -u filename ...

If for some reason you want to remove the HIP expansions from a document, there is an 'unHIP' option. Just specify the '-u' (case sensitive) on the command line before the filename(s.) All HIP operations are performed just like normal, but includes are not expanded in the output. Just HIP the document again normally to put everything back. HIP will not remove an included portion if it can't be found to put back, so this operation should be safe.

Here are a few possible reasons why you might need or want to unHIP:

• You want to edit the skeleton (it can be hard to see clearly)
• You got carried away and HIPped some include fragments, and you would like to shrink them back to size to save space and/or processing time.
• You need to convince yourself that this all works.
• You need to prepare something to put in the examples archive :)