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