The Developer Connection…ice Driver Kit for OS/2 3/DEV3-D1.ISO/devtools/ipfcpp/ipfcprep.inf

OS/2 Help File | 1994-01-24 | 16.2 KB | 622 lines

ΓòÉΓòÉΓòÉ 1. Changes ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 1.1. Version 2.1 ΓòÉΓòÉΓòÉ

All changes for release 2.0 are marked with a 'B'.

   o  Change documentation and code for external release.

   o  Increased the size of initial symbol text from 120 to 250.

   o  Changed it so that #define values that are a single value do not convert
      from hex to decimal or from octal to decimal, but rather leave the
      expression as it is.


ΓòÉΓòÉΓòÉ 1.2. Version 2.0 ΓòÉΓòÉΓòÉ

All changes for release 2.0 are marked with a 'A'.

   o  Fixed a bug where macros were case sensitive and aliasing did not work.
      Macro names are now case insensitive.

   o  Fixed a bug in nested config sections. Two nested configuration sections
      in a row were not working. The second section was being deleted if the
      first section was deleted. It now works properly.

   o  Added support for #ifdef and #ifndef. #if and #elif are ignored.

   o  Added a message for recursive macro and symbol expansion to eliminate the
      stack overflow problem.


ΓòÉΓòÉΓòÉ 1.3. Version 1.9 ΓòÉΓòÉΓòÉ

All changes for release 1.9 are marked with a '9'.

   o  Fixed a bug where periods in symbols strings were considered end of
      symbol or macro they were imbedded in.


ΓòÉΓòÉΓòÉ 1.4. Version 1.8 ΓòÉΓòÉΓòÉ

All changes for release 1.8 are marked with a '8'.

   o  Added support for nested include files

   o  Added support for not including system include files (/S)

   o  Added support for strings within string like "The string 'string'"

   o  Fixed a bug where comments on C include files caused errors.


ΓòÉΓòÉΓòÉ 1.5. Version 1.7 ΓòÉΓòÉΓòÉ

All changes for release 1.7 are marked with a '7'.

   o  Added expression evaluation support for C .H files.


ΓòÉΓòÉΓòÉ 1.6. Version 1.6 ΓòÉΓòÉΓòÉ

All changes for release 1.6 are marked with a '6'.

   o  Added /N switch to NOT resolve bitmap paths.

   o  Allowed for simple recursive symbols in C files.


ΓòÉΓòÉΓòÉ 1.7. Version 1.5 ΓòÉΓòÉΓòÉ

All changes for release 1.5 are marked with a '5'.

   o  Partially resolved nested symbols leave partial result instead of
      original symbol.

   o  All output goes to stdout instead of stderr.


ΓòÉΓòÉΓòÉ 1.8. Version 1.4 ΓòÉΓòÉΓòÉ

All changes for release 1.4 are marked with a '4'.

   o  Added /V option to display lines as they are read in

   o  Fixed nested symbol infinite loop.


ΓòÉΓòÉΓòÉ 1.9. Version 1.3 ΓòÉΓòÉΓòÉ

All changes for release 1.3 are marked with a '3'.

   o  Allowed nested symbols (symbols within symbols).

   o  Allowed positional parameters on macros.

   o  Strip double quotes off of C #define symbols so they can be used as
      normal substitution variables.

   o  Resolve bitmap file paths so that bitmaps can be in a seperate directory
      pointed to by the INCLUDE environment variable.


ΓòÉΓòÉΓòÉ 1.10. Version 1.2 ΓòÉΓòÉΓòÉ

All changes for release 1.2 are marked with a '2'.

   o  Allowed script tags for macro definitions so that the IPFCPREP macros
      will print under Bookie.


ΓòÉΓòÉΓòÉ 1.11. Version 1.1 ΓòÉΓòÉΓòÉ

All changes for release 1.1 are marked with a '1'.

   o  Added /W & -W to allow warning messages (default is now NO warning msgs)

   o  Added ability to use /D along with -D

   o  Fixed problem with command line definitions.

   o  Fixed a bug with large number of files (I forgot to close files when I
      was finished with them).


ΓòÉΓòÉΓòÉ 2. Overview ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 2.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= parameters.

   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.


ΓòÉΓòÉΓòÉ 2.2. Running IPFCPREP ΓòÉΓòÉΓòÉ

To run the IPFC preprocessor, type on the command line

IPFCPREP input_file_name output_file_name [-V] [-W] [-D symbolname[=symbol_text]]

 Name                Definition
 input_file_name     Input script file
 output_file_name    Output script file
 /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.
 /D, -D, /d, or -d   Flag to indicate a symbol definition
 /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 '<' & '>'.
 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.


ΓòÉΓòÉΓòÉ 2.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


ΓòÉΓòÉΓòÉ 3. Reference ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 3.1. Imbedding Files from Other Subdirectories ΓòÉΓòÉΓòÉ

To have the IPFC preprocessor pull in imbedded files from other subdirectories,
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.


ΓòÉΓòÉΓòÉ 3.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 subdirectories
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'.


ΓòÉΓòÉΓòÉ 3.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.


ΓòÉΓòÉΓòÉ 3.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'.


ΓòÉΓòÉΓòÉ 3.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 previously
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
compiler 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.


ΓòÉΓòÉΓòÉ 3.3.1. Example ΓòÉΓòÉΓòÉ

To include the 'test.h' C language define file in the document use the
following 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.


ΓòÉΓòÉΓòÉ 3.4. Using Bookmaster 2.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 conditional
expression. If the conditional-expression is FALSE, the opposite operation is
performed, i.e. lines will be deleted if INSERT is specified and lines will be
inserted if DELETE is specified.


ΓòÉΓòÉΓòÉ 3.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


ΓòÉΓòÉΓòÉ 3.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 parameters,
and finally a period (.). The period at the end of the macro is required.


ΓòÉΓòÉΓòÉ 3.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..


ΓòÉΓòÉΓòÉ 3.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
      uppercase.


ΓòÉΓòÉΓòÉ 3.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.


ΓòÉΓòÉΓòÉ 3.7. Using Positional Parameters on Macros ΓòÉΓòÉΓòÉ

Positional parameters *, and *1 throught *n may be used in macros instead of
keyword parameters.


ΓòÉΓòÉΓòÉ 3.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.