home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ipfcpp.zip / IPFCPREP.DOC < prev    next >
Text File  |  1992-07-15  |  18KB  |  599 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                                 INFORMATION PRESENTATION FACILITY PREPROCESSOR
  14.                                                       (C) IBM CORPORATION 1992
  15.                                                                    VERSION 1.0
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.                                                                  June 30, 1992
  24.  
  25.  
  26.                                                                     Doug Haigh
  27.  
  28.  
  29.                                                                IBM Corporation
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  Contents
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  1.0 OVERVIEW   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  45.  1.1  What IPFCPREP does for you.   . . . . . . . . . . . . . . . . . . . .  3
  46.  1.2  Running IPFCPREP  . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  47.    1.2.1  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  48.  
  49.  2.0 REFERENCE  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
  50.  2.1  Imbedding Files from Other Subdirectories   . . . . . . . . . . . . .  5
  51.    2.1.1  Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
  52.  2.2  Defining Symbols  . . . . . . . . . . . . . . . . . . . . . . . . . .  5
  53.    2.2.1  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
  54.  2.3  Using C Language define files   . . . . . . . . . . . . . . . . . . .  6
  55.    2.3.1  Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  56.  2.4  Using Bookmaster 1.0 Vanilla conditional compiles   . . . . . . . . .  7
  57.    2.4.1  Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
  58.  2.5  Using Simple Macros   . . . . . . . . . . . . . . . . . . . . . . . .  8
  59.    2.5.1  Example   . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9
  60.  2.6  Using Simple Macros that can be used in BookMaster  . . . . . . . . .  9
  61.    2.6.1  Example   . . . . . . . . . . . . . . . . . . . . . . . . . . .   10
  62.  2.7  Using Positional Parameters on Macros   . . . . . . . . . . . . . .   11
  63.    2.7.1  Example   . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
  64.  
  65.  
  66.  
  67.  
  68.  1.0  Overview
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  1.1  What IPFCPREP does for you.
  75.  
  76.  o   Allows you to have IPFC script files in different subdirectories.
  77.  
  78.      The IPFCPREP program will look at the INCLUDE environment variable as it
  79.      processes the imbed (.im) tags so that it can search more than the
  80.      current subdirectory for script files.
  81.  
  82.  o   Allows you to define symbols.
  83.  
  84.      The IPFCPREP program allows the use of BookMaster .nameit tags with the
  85.      symbol= and text= paramters.
  86.  
  87.  o   Allows you to use C language header files to define symbols.
  88.  
  89.      The IPFCPREP program will read in C language header files and use the
  90.      #define statements as BookMaster .nameit tags.
  91.  
  92.  o   Allows you to have conditional compile sections
  93.  
  94.      The IPFCPREP program supports BookMaster Vanilla conditional compiles.
  95.  
  96.  o   Allows you to have simple substitution macros.
  97.  
  98.      The IPFCPREP will support the .dm tag to define simple macros that are
  99.      used for text replacement only.  Either keyword or positional parameters
  100.      may be used.
  101.  
  102.  o   Resolves bitmap file names to fully qualified path name.
  103.  
  104.      Currently IPF requires the bitmap files be in the current directory.  If
  105.      multiple versions of a file are produced in different subdirectories, the
  106.      bitmaps must be copied into every subdirectory. IPFCPREP will resolve the
  107.      bitmap file's position using the INCLUDE environment variable and replace
  108.      the bitmap file's name with a fully qualified path name in the artwork
  109.      tag. It will also resolve the artwork linkfile's name.
  110.  
  111. ***************************************************************************
  112.  1.2  Running IPFCPREP
  113.  
  114.  To run the IPFC preprocessor, type on the command line
  115.  
  116.  IPFCPREP input_file_name output_file_name [options]
  117.  
  118.  NAME                DEFINITION
  119.  
  120.  input_file_name     Input script file
  121.  
  122.  output_file_name    Output script file
  123.  
  124.  options             Preprocessing options
  125.  
  126.    /V, -V, /v, OR -v   Flag to indicate you want lines printed out as they are
  127.                        read in
  128.  
  129.    /W, -W, /w, OR -w   Flag to indicate you want additional warning messages.
  130.  
  131.  
  132.    /N, -N, /n, OR -n   Flag to indicate a symbol definition
  133.  
  134.    /S, -S, /s, OR -s   Flag to indicate not to include system include files,
  135.                        i.e. files that are enclosed by '<' & '>'.
  136.  
  137.    /D, -D, /d, OR -d   Flag to indicate a symbol definition of the form
  138.                        -D symbolname[=symbol_text] where
  139.  
  140.      symbolname          Name of symbol to be defined
  141.  
  142.      symbol_text         Text of defined symbol.
  143.  
  144.                          This is optional.  If no symbol_text is defined, the
  145.                          symbol is put in the symbol table with no text
  146.                          (ex: for use on conditional compiles).  If text is
  147.                          defined, it can either be a single word or multiple
  148.                          words inclosed in single quotes.
  149.  
  150.  1.2.1  Examples
  151.  
  152.  The following will preprocess the test.scr file into the test.ipf file.
  153.  
  154.    ipfcprep test.scr test.ipf
  155.  
  156.  The following will preprocess the test.scr file into the test.ipf file and
  157.  define one symbol called HOST.
  158.  
  159.    ipfcprep test.scr test.ipf -D HOST
  160.  
  161.  The following will preprocess the test.scr file into the test.ipf file and
  162.  define one symbol called HOST with the text Mainframe.
  163.  
  164.    ipfcprep test.scr test.ipf -D HOST=MainFrame
  165.  
  166.  The following will preprocess the test.scr file into the test.ipf file and
  167.  define one symbol called HOST with the text IBM Mainframe.
  168.  
  169.    ipfcprep test.scr test.ipf -D HOST='IBM MainFrame'
  170.  
  171.  The following will preprocess the test.scr file into the test.ipf file,
  172.  define one symbol called HOST with the text IBM Mainframe, and define a
  173.  symbol called PC
  174.  
  175.    ipfcprep test.scr test.ipf -D HOST='IBM MainFrame' -D PC
  176.  
  177.  The following will preprocess the test.scr file into the test.ipf file,
  178.  define one symbol called HOST with the text IBM Mainframe, define a symbol
  179.  called PC and turn on those annoying warning messages.
  180.  
  181.    ipfcprep test.scr test.ipf -D HOST='IBM MainFrame' /D PC /W
  182.  
  183.  
  184.  
  185.  2.0  Reference
  186.  
  187.  
  188.  
  189.  
  190. ***************************************************************************
  191.  2.1  Imbedding Files from Other Subdirectories
  192.  
  193.  To have the IPFC preprocessor pull in imbedded files from other subdirecto-
  194.  ries, set up the INCLUDE environment variable with the path(s) to search.
  195.  
  196.  IPFCPREP will also resolve the bitmap name or linkfile name in an artwork tag
  197.  using the INCLUDE environment variable.  This can be turned off using the /N
  198.  switch on the command line.
  199.  
  200.  
  201.  2.1.1  Example
  202.  
  203.  After the include environment variable is set as shown by the following
  204.  command, the IPFCPREP will search the C:\HELPDIR1 & C:\HELPDIR2 subdirecto-
  205.  ries after checking the current subdirectory for an imbed file.
  206.  
  207.    SET INCLUDE=C:\HELPDIR1;C:\HELPDIR2;
  208.  
  209.  For artwork tags, resolving will make a artwork tag that looks like
  210.  
  211.    :artwork name='IPFCPREP.BMP' linkfile='IPFCPREP.LNK'.
  212.  
  213.  into a tag that looks like
  214.  
  215.    :artwork name='C:\HELPDIR1\IPFCPREP.BMP' linkfile='C:\HELPDIR1\IPFCPREP.LNK'.
  216.  
  217.  
  218. ***************************************************************************
  219.  2.2  Defining Symbols
  220.  
  221.  To define symbols, use the same method as in BookMaster with .nameit tags.
  222.  IPFCPREP does not allow the GMLTYPE or SIZE parameters however. If you want
  223.  those, you must create a simple macro described later.
  224.  
  225.  To use the symbol in the file, put an ampersand (&) before the symbol and a
  226.  period (.) after it. The period after the symbol is required.
  227.  
  228.  Symbols may be within symbols (nested symbols). The innermost symbol will be
  229.  resolved first and then the resulting text will be used to search for the
  230.  remaining symbol.
  231.  
  232.  Currently, the maximum symbol size after everything is resolved is about 250
  233.  character bytes.
  234.  
  235.  
  236.  2.2.1  Examples
  237.  
  238.  The following line will create a symbol called goofy and a symbol called MM
  239.  with the text for the first being 'Goofy' and the second being 'Mickey
  240.  Mouse'.
  241.  
  242.    .nameit symbol=goofy text='Goofy'
  243.    .nameit symbol=MM text='Mickey Mouse'
  244.  
  245.  Now if those are used in the following sentences
  246.  
  247.    I went to Disney World and saw &goofy. and &MM..
  248.  
  249.  The text will come out like
  250.  
  251.    I went to Disney World and saw Goofy and Mickey Mouse.
  252.  
  253.  The following demonstrates the use of nested symbols.
  254.  
  255.    .nameit symbol=mightm text='Mighty Mouse'
  256.    .nameit symbol=mickm text='Mickey Mouse'
  257.  
  258.  Now if those are used in the following sentence
  259.  
  260.    I went to Disney World and saw  &&mouse_name.m..
  261.  
  262.  The text will come out like
  263.  
  264.    I went to Disney World and saw Mickey Mouse.
  265.  
  266.  when &mouse_name. is set to 'mick', or it will come out like
  267.  
  268.    I went to Disney World and saw Mighty Mouse.
  269.  
  270.  when &mouse_name. is set to 'might'.
  271.  
  272.  
  273.  
  274. ***************************************************************************
  275.  2.3  Using C Language define files
  276.  
  277.  To use symbols in a C language header files, you must use the .imd tag to
  278.  imbed the header file. Then all defines of the form
  279.  
  280.    #define symbol_name integer_value
  281.  
  282.  or
  283.  
  284.    #define symbol_name "string"
  285.  
  286.  or
  287.  
  288.    #define symbol_name2 symbol_name1
  289.  
  290.  or
  291.  
  292.    #define symbol_name expression
  293.  
  294.  will be put into the symbol table.
  295.  
  296.  The integer version is mainly used in defining the resource id on a :h1. tag
  297.  so that you can have one file define your panel resource IDs.
  298.  
  299.  The string version is used to define text symbols similar to .namemit tags.
  300.  Wherever symbol_name is used the string (without the double quotes) will be
  301.  substituted. This is useful in using the same string that is in a .MRI file
  302.  in the text for a help panel to eliminate differences.
  303.  
  304.  The symbol set to another symbol is a method to assign the same value to two
  305.  different symbol names. If the value after a symbol name matches any previ-
  306.  ously defined symbol name (whether it be C #defines or .nameit tags) the
  307.  value of the previously defined symbol will be used.
  308.  
  309.  The symbol set to an expression is commonly used in C header files to base
  310.  all symbols off of one with an offset such as the following:
  311.  
  312.    #define START   1000
  313.    #define PANEL_1 (START + 1)
  314.    #define PANEL_2 (START + 2)
  315.  
  316.  IPFCPREP will allow the +, -, *, and / operators. It will evaluate
  317.  expressions from left to right without regard to operator precedence. If you
  318.  want precedence, you can use parentheses.
  319.  
  320.  This will also search all subdirectories defined by the INCLUDE environment
  321.  variable after searching the current directory for the specified file.
  322.  
  323.  An include file can include other include files defined by the #include com-
  324.  piler directive. You can disable the including of system include files by
  325.  using the /S command line option. This will not include any #include file
  326.  that is enclosed in '< >'.
  327.  
  328.  Currently, the maximum symbol size after everything is resolved is about 120
  329.  character bytes.
  330.  
  331.  
  332.  
  333.  IPFCPREP now supports some compiler directives, namely, #ifdef and #ifndef.
  334.  IPFCPREP will determine if the symbol referenced by these lines exists or not
  335.  and process or not process the lines that follow. #else used with #ifdefs or
  336.  #ifndefs is also allowed.
  337.  
  338.  IPFCPREP does not handle the #if or #elif lines currently due to IPFCPREP's
  339.  lack of logical expression evaluation. #else used with #if or #elif is
  340.  ignored also.
  341.  
  342.  
  343.  2.3.1  Example
  344.  
  345.  To include the 'test.h' C language define file in the document use the fol-
  346.  lowing line in the script file
  347.  
  348.    .imd test.h
  349.  
  350.  Now if the C header file had the statement
  351.  
  352.    #define HELP_PANEL_1 100
  353.  
  354.  And the script file contained the line
  355.  
  356.    :h1 res=&HELP_PANEL_1..
  357.  
  358.  The preprocessor will resolve it to
  359.  
  360.    :h1 res=100.
  361.  
  362.  
  363. ***************************************************************************
  364.  2.4  Using Bookmaster 1.0 Vanilla conditional compiles
  365.  
  366.  The best reference for this is the BookMaster document, but I will put a
  367.  short exerpt here.
  368.  
  369.  The conditional compiles use two main tags, the .CONFIG & .WHEN tags.
  370.  .CONFIG tags start and end conditional compile sections and the .WHEN tags
  371.  instruct the preprocessor to insert or delete lines based on a conditions.
  372.  
  373.  The .CONFIG tag looks like
  374.  
  375.    .CONFIG config_name ON | OFF
  376.  
  377.  The config_name is used to match the ON and OFF statements. Nested config
  378.  statements are allowed.
  379.  
  380.  The .WHEN tag looks like
  381.  
  382.    .WHEN 'condition-expression' INSERT | DELETE
  383.  
  384.  The condition-expression is a symbol or group of symbols that are defined or
  385.  not defined to determine if the expression is TRUE. This may take the form of
  386.  
  387.    'symbol1 symbol2 ... symboln'
  388.  
  389.  which will AND the symbols together or
  390.  
  391.    'symbol1 or symbol2 or ... or symboln'
  392.  
  393.  which will OR the symbols together. Symbols may also be negated such as
  394.  
  395.    'not symbol1 or symbol2'
  396.  
  397.  When the condition is TRUE, the lines following the .WHEN line are either
  398.  inserted or deleted depending on the INSERT or DELETE following the condi-
  399.  tional expression. If the conditional-expression is FALSE, the opposite oper-
  400.  ation is performed, i.e. lines will be deleted if INSERT is specified and
  401.  lines will be inserted if DELETE is specified.
  402.  
  403.  
  404.  2.4.1  Example
  405.  
  406.  For example, the conditional compile
  407.  
  408.    .config section1 on
  409.    .when 'PC' insert
  410.    This is processed on a PC.
  411.    .when 'HOST' insert
  412.    This is processed on the big iron.
  413.    .config section1 off
  414.  
  415.  will produce 'This is processed on a PC.' when IPFCPREP is invoked like
  416.  
  417.    ipfcprep in.scr out.ipf -D PC
  418.  
  419.  and will produce 'This is processed on the big iron.' when IPFCPREP is
  420.  invoked like
  421.  
  422.    ipfcprep in.scr out.ipf -D HOST
  423.  
  424.  
  425.  
  426. ***************************************************************************
  427.  2.5  Using Simple Macros
  428.  
  429.  Macros in the IPFCPREP is a simple way to substitute lines of text for a
  430.  single tag. This does not do any math or fancy macro stuff, just simple text
  431.  substitution.
  432.  
  433.  Macros start with a '.dm macro-name on' tag and end with a '.dm off' tag. All
  434.  text between the those two lines is part of the macro.
  435.  
  436.  The macro is invoked by specifying a colon (:), the macro name, any parame-
  437.  ters, and finally a period (.). The period at the end of the macro is
  438.  required.
  439.  
  440.  
  441.  2.5.1  Example
  442.  
  443.  For example, the macro
  444.  
  445.    .dm testmac on
  446.    This macro prints out &text. when invoked
  447.    .dm off
  448.  
  449.  will produce
  450.  
  451.    This macro prints out garbage when invoked.
  452.  
  453.  when it is called like
  454.  
  455.    :testmac text=garbage.
  456.  
  457.  It will also produce
  458.  
  459.    This macro prints out tons of garbage when invoked.
  460.  
  461.  when it is called like
  462.  
  463.    :testmac text='tons of garbage'.
  464.  
  465.  Another example, the macro
  466.  
  467.    .dm user_resp on
  468.    :hp1.&resp.:ehp1.
  469.    .dm off
  470.  
  471.  will produce
  472.  
  473.    The user response is :hp1.Quit:ehp1..
  474.  
  475.  when it is called like
  476.  
  477.    The user response is :user_resp resp=Quit..
  478.  
  479.  
  480.  
  481. ***************************************************************************
  482.  2.6  Using Simple Macros that can be used in BookMaster
  483.  
  484.  To make these macros work under BookMaster, you must structure the macro
  485.  slightly different. You must
  486.  
  487.  o   Add a '.gs attval parm_keyname_1 parm_keyname2 ...' line after the '.dm
  488.      macro_name' line so that the values are assigned in BookMaster.
  489.  
  490.  o   Add a '.aa tag_name start_macro_name end_macro_name' after the '.dm off'
  491.      line so that you can reference the macros start_macro_name and
  492.      end_macro_name by :tag_name. & :etag_name.
  493.  
  494.  o   Make sure all substitution variables on the tag line are used in upper-
  495.      case.
  496.  
  497.  
  498.  2.6.1  Example
  499.  
  500.  For example, the macro
  501.  
  502.    .dm testmac on
  503.    .gs attval text
  504.    This macro prints out &TEXT. when invoked
  505.    .dm off
  506.    .aa test testmac
  507.  
  508.  will produce
  509.  
  510.    This macro prints out garbage when invoked.
  511.  
  512.  when it is called like
  513.  
  514.    :test text=garbage.
  515.  
  516.  It will also produce
  517.  
  518.    This macro prints out tons of garbage when invoked.
  519.  
  520.  when it is called like
  521.  
  522.    :test text='tons of garbage'.
  523.  
  524.  Another example, the macro
  525.  
  526.    .dm strtlist on
  527.    :ul.
  528.    .dm off
  529.  
  530.    .dm endlist on
  531.    :eul.
  532.    .dm off
  533.  
  534.    .aa list strtlist endlist
  535.  
  536.    .dm listitem on
  537.    :li.
  538.    .dm off
  539.  
  540.    .aa item listitem
  541.  
  542.  
  543.  
  544.  will produce
  545.  
  546.    :ul.
  547.    :li.Text
  548.    :eul.
  549.  
  550.  when it is called like
  551.  
  552.    :list.
  553.    :item.Text
  554.    :elist.
  555.  
  556. ***************************************************************************
  557.  2.7  Using Positional Parameters on Macros
  558.  
  559.  Positional parameters *, and *1 throught *n may be used in macros instead of
  560.  keyword parameters.
  561.  
  562.  
  563.  2.7.1  Example
  564.  
  565.  For example, the macro
  566.  
  567.    .dm posmac on
  568.    All parms are :*..
  569.    This is the first parm = &*1..
  570.    This is the second parm = &*2..
  571.    This is the third parm = &*3..
  572.    This is the fourth parm = &*4..
  573.    . off
  574.  
  575.  will produce
  576.  
  577.    All parms are Mickey Mouse loves Minnie.
  578.    This is the first parm = Mickey.
  579.    This is the second parm = Mouse.
  580.    This is the third parm = loves.
  581.    This is the fourth parm = Minnie.
  582.  
  583.  when it is called like
  584.  
  585.    :posmac Mickey Mouse loves Minnie.
  586.  
  587.  It will also produce
  588.  
  589.    All parms are Mickey Mouse loves nobody.
  590.    This is the first parm = Mickey.
  591.    This is the second parm = Mouse.
  592.    This is the third parm = loves.
  593.    This is the fourth parm = nobody.
  594.  
  595.  when it is called like
  596.  
  597.    :posmac Mickey Mouse loves nobody.
  598.  
  599.