INFORMATION PRESENTATION FACILITY PREPROCESSOR
(C) IBM CORPORATION 1992
VERSION 1.0
June 30, 1992
Doug Haigh
IBM Corporation
Contents
1.0 OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 What IPFCPREP does for you. . . . . . . . . . . . . . . . . . . . . 3
1.2 Running IPFCPREP . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.0 REFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1 Imbedding Files from Other Subdirectories . . . . . . . . . . . . . 5
2.1.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Defining Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Using C Language define files . . . . . . . . . . . . . . . . . . . 6
2.3.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4 Using Bookmaster 1.0 Vanilla conditional compiles . . . . . . . . . 7
2.4.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.5 Using Simple Macros . . . . . . . . . . . . . . . . . . . . . . . . 8
2.5.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.6 Using Simple Macros that can be used in BookMaster . . . . . . . . . 9
2.6.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.7 Using Positional Parameters on Macros . . . . . . . . . . . . . . 11
2.7.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.0 Overview
1.1 What IPFCPREP does for you.
o Allows you to have IPFC script files in different subdirectories.
The IPFCPREP program will look at the INCLUDE environment variable as it
processes the imbed (.im) tags so that it can search more than the
current subdirectory for script files.
o Allows you to define symbols.
The IPFCPREP program allows the use of BookMaster .nameit tags with the
symbol= and text= paramters.
o Allows you to use C language header files to define symbols.
The IPFCPREP program will read in C language header files and use the
#define statements as BookMaster .nameit tags.
o Allows you to have conditional compile sections
The IPFCPREP program supports BookMaster Vanilla conditional compiles.
o Allows you to have simple substitution macros.
The IPFCPREP will support the .dm tag to define simple macros that are
used for text replacement only. Either keyword or positional parameters
may be used.
o Resolves bitmap file names to fully qualified path name.
Currently IPF requires the bitmap files be in the current directory. If
multiple versions of a file are produced in different subdirectories, the
bitmaps must be copied into every subdirectory. IPFCPREP will resolve the
bitmap file's position using the INCLUDE environment variable and replace
the bitmap file's name with a fully qualified path name in the artwork
tag. It will also resolve the artwork linkfile's name.
***************************************************************************
1.2 Running IPFCPREP
To run the IPFC preprocessor, type on the command line
IPFCPREP input_file_name output_file_name [options]
NAME DEFINITION
input_file_name Input script file
output_file_name Output script file
options Preprocessing options
/V, -V, /v, OR -v Flag to indicate you want lines printed out as they are
read in
/W, -W, /w, OR -w Flag to indicate you want additional warning messages.
/N, -N, /n, OR -n Flag to indicate a symbol definition
/S, -S, /s, OR -s Flag to indicate not to include system include files,
i.e. files that are enclosed by '<' & '>'.
/D, -D, /d, OR -d Flag to indicate a symbol definition of the form
-D symbolname[=symbol_text] where
symbolname Name of symbol to be defined
symbol_text Text of defined symbol.
This is optional. If no symbol_text is defined, the
symbol is put in the symbol table with no text
(ex: for use on conditional compiles). If text is
defined, it can either be a single word or multiple
words inclosed in single quotes.
1.2.1 Examples
The following will preprocess the test.scr file into the test.ipf file.
ipfcprep test.scr test.ipf
The following will preprocess the test.scr file into the test.ipf file and
define one symbol called HOST.
ipfcprep test.scr test.ipf -D HOST
The following will preprocess the test.scr file into the test.ipf file and
define one symbol called HOST with the text Mainframe.
ipfcprep test.scr test.ipf -D HOST=MainFrame
The following will preprocess the test.scr file into the test.ipf file and
define one symbol called HOST with the text IBM Mainframe.
ipfcprep test.scr test.ipf -D HOST='IBM MainFrame'
The following will preprocess the test.scr file into the test.ipf file,
define one symbol called HOST with the text IBM Mainframe, and define a
symbol called PC
ipfcprep test.scr test.ipf -D HOST='IBM MainFrame' -D PC
The following will preprocess the test.scr file into the test.ipf file,
define one symbol called HOST with the text IBM Mainframe, define a symbol
called PC and turn on those annoying warning messages.
ipfcprep test.scr test.ipf -D HOST='IBM MainFrame' /D PC /W
2.0 Reference
***************************************************************************
2.1 Imbedding Files from Other Subdirectories
To have the IPFC preprocessor pull in imbedded files from other subdirecto-
ries, set up the INCLUDE environment variable with the path(s) to search.
IPFCPREP will also resolve the bitmap name or linkfile name in an artwork tag
using the INCLUDE environment variable. This can be turned off using the /N
switch on the command line.
2.1.1 Example
After the include environment variable is set as shown by the following
command, the IPFCPREP will search the C:\HELPDIR1 & C:\HELPDIR2 subdirecto-
ries after checking the current subdirectory for an imbed file.
SET INCLUDE=C:\HELPDIR1;C:\HELPDIR2;
For artwork tags, resolving will make a artwork tag that looks like
:artwork name='IPFCPREP.BMP' linkfile='IPFCPREP.LNK'.
into a tag that looks like
:artwork name='C:\HELPDIR1\IPFCPREP.BMP' linkfile='C:\HELPDIR1\IPFCPREP.LNK'.
***************************************************************************
2.2 Defining Symbols
To define symbols, use the same method as in BookMaster with .nameit tags.
IPFCPREP does not allow the GMLTYPE or SIZE parameters however. If you want
those, you must create a simple macro described later.
To use the symbol in the file, put an ampersand (&) before the symbol and a
period (.) after it. The period after the symbol is required.
Symbols may be within symbols (nested symbols). The innermost symbol will be
resolved first and then the resulting text will be used to search for the
remaining symbol.
Currently, the maximum symbol size after everything is resolved is about 250
character bytes.
2.2.1 Examples
The following line will create a symbol called goofy and a symbol called MM
with the text for the first being 'Goofy' and the second being 'Mickey
Mouse'.
.nameit symbol=goofy text='Goofy'
.nameit symbol=MM text='Mickey Mouse'
Now if those are used in the following sentences
I went to Disney World and saw &goofy. and &MM..
The text will come out like
I went to Disney World and saw Goofy and Mickey Mouse.
The following demonstrates the use of nested symbols.
.nameit symbol=mightm text='Mighty Mouse'
.nameit symbol=mickm text='Mickey Mouse'
Now if those are used in the following sentence
I went to Disney World and saw &&mouse_name.m..
The text will come out like
I went to Disney World and saw Mickey Mouse.
when &mouse_name. is set to 'mick', or it will come out like
I went to Disney World and saw Mighty Mouse.
when &mouse_name. is set to 'might'.
***************************************************************************
2.3 Using C Language define files
To use symbols in a C language header files, you must use the .imd tag to
imbed the header file. Then all defines of the form
#define symbol_name integer_value
or
#define symbol_name "string"
or
#define symbol_name2 symbol_name1
or
#define symbol_name expression
will be put into the symbol table.
The integer version is mainly used in defining the resource id on a :h1. tag
so that you can have one file define your panel resource IDs.
The string version is used to define text symbols similar to .namemit tags.
Wherever symbol_name is used the string (without the double quotes) will be
substituted. This is useful in using the same string that is in a .MRI file
in the text for a help panel to eliminate differences.
The symbol set to another symbol is a method to assign the same value to two
different symbol names. If the value after a symbol name matches any previ-
ously defined symbol name (whether it be C #defines or .nameit tags) the
value of the previously defined symbol will be used.
The symbol set to an expression is commonly used in C header files to base
all symbols off of one with an offset such as the following:
#define START 1000
#define PANEL_1 (START + 1)
#define PANEL_2 (START + 2)
IPFCPREP will allow the +, -, *, and / operators. It will evaluate
expressions from left to right without regard to operator precedence. If you
want precedence, you can use parentheses.
This will also search all subdirectories defined by the INCLUDE environment
variable after searching the current directory for the specified file.
An include file can include other include files defined by the #include com-
piler directive. You can disable the including of system include files by
using the /S command line option. This will not include any #include file
that is enclosed in '< >'.
Currently, the maximum symbol size after everything is resolved is about 120
character bytes.
IPFCPREP now supports some compiler directives, namely, #ifdef and #ifndef.
IPFCPREP will determine if the symbol referenced by these lines exists or not
and process or not process the lines that follow. #else used with #ifdefs or
#ifndefs is also allowed.
IPFCPREP does not handle the #if or #elif lines currently due to IPFCPREP's
lack of logical expression evaluation. #else used with #if or #elif is
ignored also.
2.3.1 Example
To include the 'test.h' C language define file in the document use the fol-
lowing line in the script file
.imd test.h
Now if the C header file had the statement
#define HELP_PANEL_1 100
And the script file contained the line
:h1 res=&HELP_PANEL_1..
The preprocessor will resolve it to
:h1 res=100.
***************************************************************************
2.4 Using Bookmaster 1.0 Vanilla conditional compiles
The best reference for this is the BookMaster document, but I will put a
short exerpt here.
The conditional compiles use two main tags, the .CONFIG & .WHEN tags.
.CONFIG tags start and end conditional compile sections and the .WHEN tags
instruct the preprocessor to insert or delete lines based on a conditions.
The .CONFIG tag looks like
.CONFIG config_name ON | OFF
The config_name is used to match the ON and OFF statements. Nested config
statements are allowed.
The .WHEN tag looks like
.WHEN 'condition-expression' INSERT | DELETE
The condition-expression is a symbol or group of symbols that are defined or
not defined to determine if the expression is TRUE. This may take the form of
'symbol1 symbol2 ... symboln'
which will AND the symbols together or
'symbol1 or symbol2 or ... or symboln'
which will OR the symbols together. Symbols may also be negated such as
'not symbol1 or symbol2'
When the condition is TRUE, the lines following the .WHEN line are either
inserted or deleted depending on the INSERT or DELETE following the condi-
tional expression. If the conditional-expression is FALSE, the opposite oper-
ation is performed, i.e. lines will be deleted if INSERT is specified and
lines will be inserted if DELETE is specified.
2.4.1 Example
For example, the conditional compile
.config section1 on
.when 'PC' insert
This is processed on a PC.
.when 'HOST' insert
This is processed on the big iron.
.config section1 off
will produce 'This is processed on a PC.' when IPFCPREP is invoked like
ipfcprep in.scr out.ipf -D PC
and will produce 'This is processed on the big iron.' when IPFCPREP is
invoked like
ipfcprep in.scr out.ipf -D HOST
***************************************************************************
2.5 Using Simple Macros
Macros in the IPFCPREP is a simple way to substitute lines of text for a
single tag. This does not do any math or fancy macro stuff, just simple text
substitution.
Macros start with a '.dm macro-name on' tag and end with a '.dm off' tag. All
text between the those two lines is part of the macro.
The macro is invoked by specifying a colon (:), the macro name, any parame-
ters, and finally a period (.). The period at the end of the macro is
required.
2.5.1 Example
For example, the macro
.dm testmac on
This macro prints out &text. when invoked
.dm off
will produce
This macro prints out garbage when invoked.
when it is called like
:testmac text=garbage.
It will also produce
This macro prints out tons of garbage when invoked.
when it is called like
:testmac text='tons of garbage'.
Another example, the macro
.dm user_resp on
:hp1.&resp.:ehp1.
.dm off
will produce
The user response is :hp1.Quit:ehp1..
when it is called like
The user response is :user_resp resp=Quit..
***************************************************************************
2.6 Using Simple Macros that can be used in BookMaster
To make these macros work under BookMaster, you must structure the macro
slightly different. You must
o Add a '.gs attval parm_keyname_1 parm_keyname2 ...' line after the '.dm
macro_name' line so that the values are assigned in BookMaster.
o Add a '.aa tag_name start_macro_name end_macro_name' after the '.dm off'
line so that you can reference the macros start_macro_name and
end_macro_name by :tag_name. & :etag_name.
o Make sure all substitution variables on the tag line are used in upper-
case.
2.6.1 Example
For example, the macro
.dm testmac on
.gs attval text
This macro prints out &TEXT. when invoked
.dm off
.aa test testmac
will produce
This macro prints out garbage when invoked.
when it is called like
:test text=garbage.
It will also produce
This macro prints out tons of garbage when invoked.
when it is called like
:test text='tons of garbage'.
Another example, the macro
.dm strtlist on
:ul.
.dm off
.dm endlist on
:eul.
.dm off
.aa list strtlist endlist
.dm listitem on
:li.
.dm off
.aa item listitem
will produce
:ul.
:li.Text
:eul.
when it is called like
:list.
:item.Text
:elist.
***************************************************************************
2.7 Using Positional Parameters on Macros
Positional parameters *, and *1 throught *n may be used in macros instead of
keyword parameters.
2.7.1 Example
For example, the macro
.dm posmac on
All parms are :*..
This is the first parm = &*1..
This is the second parm = &*2..
This is the third parm = &*3..
This is the fourth parm = &*4..
. off
will produce
All parms are Mickey Mouse loves Minnie.
This is the first parm = Mickey.
This is the second parm = Mouse.
This is the third parm = loves.
This is the fourth parm = Minnie.
when it is called like
:posmac Mickey Mouse loves Minnie.
It will also produce
All parms are Mickey Mouse loves nobody.
This is the first parm = Mickey.
This is the second parm = Mouse.
This is the third parm = loves.
This is the fourth parm = nobody.
when it is called like
:posmac Mickey Mouse loves nobody.