Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD2.mdf / c / library / os2 / ipfedit / ipfedoc.inf (.txt) < prev next >

Wrap

OS/2 Help File | 1993-08-14 | 91.8 KB | 2,304 lines

ΓòÉΓòÉΓòÉ 1. IPF Editor Overview ΓòÉΓòÉΓòÉ Welcome to the IPF Editor, the easiest to use and most powerful editor designed specifically for creating both online documentation and online help files for your applications. There are currently two versions of the IPF Editor available. The first is a 15-usage trial version with some options disabled. The second is a registered version that must be purchased from PCS and includes many more features, customer support, updates, a complete tutorial, samples, and much more! The IPF Editor IPF Commands menu provides you with a large variety of IPF tags to choose from. Some commands require you to mark text (highlight it) before selecting the command. All IPF Commands are available from the IPF Editor's IPF Commands menu. If an IPF command is not available (it is "grayed out") it is because it requires marked text to operate correctly. You can use the mouse to mark the desired text, then select the tagging command you want to apply to the marked text. ΓòÉΓòÉΓòÉ 1.1. Software Requirements ΓòÉΓòÉΓòÉ The IPF Editor is a 32-bit OS/2 2.x application and requires OS/2 2.0, 2.01, or 2.1. The IPF tagged files it generates may be used with any OS/2 application (1.x or 2.x). To make full use of the IPF Editor you will need to have either the IBM OS/2 2.0 or 2.1 Toolkit (which contains the IPF Compiler) or a compatible product. There is a problem with the OS/2 2.01 Service Pack version of Trident video drivers. Dragging dialog boxes across the IPF Editor screen can cause a protection error in PMWIN.DLL and stop the program. THIS IS NOT DIRECTLY SOLVABLE, so if you are using the 2.01 service pack in SVGA modes, don't drag dialog boxes across your IPF Editor screens! ΓòÉΓòÉΓòÉ 1.2. Registration ΓòÉΓòÉΓòÉ The IPF Editor is both a shareware and commercial product. The shareware version gives you a fifteen usage trial period to try out the product. If after trying it you find it of value register it and receive the full package which provides automatic online-help generation for use with any C-based or C++ based OS/2 2.x application you are building. You may register it by filling out the registration/order card and sending $95.00 U.S. to Perez Computing Services at the address written below. Washington state residents add 7.8% sales tax. Please use the provide form in file: IPFEDIT.REG when ordering. Sorry, no VISA or MASTERCARD orders, please. Compuserve: 70410, 2416 Prodigy: GFKM03A Perez Computing Services 4725 Monte Vista Pl. Mount Vernon, WA 98273 ΓòÉΓòÉΓòÉ 1.3. Copyright and Notices ΓòÉΓòÉΓòÉ The IPF Editor is Copyright (C) 1992-1993 Perez Computing Services. ΓòÉΓòÉΓòÉ 1.4. Reporting Problems ΓòÉΓòÉΓòÉ The IPF Editor has been thoroughly tested over the last year but occasionally bugs or problems are reported. If you find a problem, or have a suggestion for a new feature, please contact PCS, attention Bill Perez, either through Compuserve, Prodigy, or the U.S. mail. ΓòÉΓòÉΓòÉ 2. Using the IPF Editor ΓòÉΓòÉΓòÉ The IPF Editor display is broken up into several sections as shown in the figure below: The IPF Editor supports all standard OS/2 editing commands (Marking text, copying, cutting, deleting marked text, pasting text into the document from the clipboard, undo, etc.). The arrow keys move the cursor in the editing window. The IPF Editor also has a second window that will show you the results of using the IPF Compiler. It looks similar to the following: For more detail on compiling files see the "Compiler Setup" section of this reference. ΓòÉΓòÉΓòÉ 2.1. IPF File OverView ΓòÉΓòÉΓòÉ IPF Files are text files that are "tagged" with special commands that are recognized by the IBM IPF Compiler. The IPF Compiler then generates either .HLP or .INF files that may be used with applications (.HLP files) or the OS/2 VIEW.EXE program (.INF files). IPF files are created by generating panels. A panel is a section of text that will be grouped together and placed in one window when it is displayed by either the help manager in your application or the VIEW program supplied with OS/2. Each panel has a title which is displayed at the top of the window containing the text. You are currently looking at the panel titled "IPF File OverView." Each panel will also be placed in the table of contents for the document. You can split your document into several different files, each with specific panels, and group the entire document together using the IPF Editor's "File Create Project" command. ΓòÉΓòÉΓòÉ 2.2. Graphical Tool Menu ΓòÉΓòÉΓòÉ The graphical tool menu at the right side of the IPF Editor window provides you with several tools to quickly edit documents. If the graphical menu doesn't completely fit in your current window, you can use the scroll bar at the right side of the IPF Editor window to view the rest of it. You may disable the graphical menu to increase the size of the editing window using the "Options, Show Graphical Menu" option. The following options are available in the graphical menu: The lets you define heading level one tags (just as if you had used the IPF commands, Panel Headers 1 menu option). The lets you define heading level two tags (just as if you had used the IPF commands, Panel Headers 2 menu option). The lets you define heading level three tags (just as if you had used the IPF commands, Panel Headers 3 menu option). The lets you insert a paragraph marker at the current location. This is the same as pressing the right mouse button and releasing it while the "Paragraph" menu option is highlighted, or using the IPF commands, paragraph option. The lets you mark a section of text as a table. The lets you insert artwork (OS/2 bitmaps or OS/2 metafiles) into your document. The lets you insert a note into your document. The lets you define a footnote link in your document. The lets you mark an area of text as a simple list. The lets you mark an area of text as an ordered list. The lets you mark an area of text as an unordered list. The lets you create an index entry. The lets you mark a selection of text as a "CAUTION:" statement. The lets you mark a selection of text as a "WARNING:" statement. The lets you insert a symbol into your document at the current location. The lets you mark selected text as being aligned left or right. The lets you setup the push button controls located at the bottom of the help or VIEW window. The lets you generate hyperlinks to other portions of your document. The allows you to save the current file to disk. The lets you save a new file to disk (it lets you give it a new name). The lets you select a project file to work on. The lets you compile the current file or project. The lets you locate text in your document. ΓòÉΓòÉΓòÉ 2.3. Creating Online Documents Overview ΓòÉΓòÉΓòÉ To create on online document perform the following steps: o Enter all text that you wish to include in your document, or import text from a word processor. o Mark the document using the standard IPF commands available in the IPF Editor or enter them manually if they are available in the IPF Guide but not directly supported by the IPF Editor. You do not need to manually enter hypertext/graphics links at this time. o Create a project by selecting the files to be included in your document using the Create Project. All files must be in the same directory. Be sure to sort the files in the order you want to see their panel headers show up in the file's table of contents. Generally this isn't a consideration for online help projects but it is very important for online documents. Use the Compiler Compile Project option to generate your online document. If any errors are detected double click with the left mouse button on the error shown in the Compiler Results window. This takes you to the error in the IPF file. Fix the error, then compile again until no errors are detected. o Once all errors are corrected test your online document using the Compiler Test Document option. o When the document is correct use the "Application Generate Auto-hypertext/graphics link" menu to automatically create hypertext/graphics links for all panel headers in your document. o Test your document for accuracy and verify the compile took place with no errors. That's all you have to know to create an online document! ΓòÉΓòÉΓòÉ 2.4. Creating Online Help Files Overview ΓòÉΓòÉΓòÉ To create on online help files perform the following steps: Create an online help project selecting the "File Create Project" option. Then scan the resource files associated with your application using the "Generate Panels from RC" files option. Several files will automatically be created for you containing panel headers for menus, submenus, menu items, dialog boxes, and dialog box items. Be sure to select the "online help" radio button to select the type of project you are creating. o Mark the IPF files using the standard IPF commands available in the IPF Editor or enter them manually if they are available in the IPF Guide but not directly supported by the IPF Editor. You do not need to manually enter hypertext/graphics links at this time. Or ever. Use the "Compiler Compile Project" option to generate your online help file. If any errors are detected double click with the left mouse button on the error shown in the Compiler Results window. This will take you directly to the place where the error was reported. Fix the error, then compile again until no errors are detected. o Use the "Application Create help resource tables" to create the help resource tables (a .RC file), a C include file (.H), and the C functions needed to initialize and call the help manager (in a .C file). o Include the help resource file created by the IPF Editor in your application's resource file using the "rcinclude" command (part of the resource script language). Then compile your application. Also compile and link the C file into your application. Use the "HelpInit()" function to initialize the help system. Call "HelpProcessMessages" when your application processes the WM_ACTIVATE, WM_INITMENU, and WM_COMMAND messages. Finally, call "HelpDestroy" before terminating your application. o When the document is correct use the "Application Generate Auto-hypertext/graphics link" menu to automatically create hypertext/graphics links for all panel headers in your document. o Test your document for accuracy and verify the compile took place with no errors. Test each entry in your application by pressing F1 on each item and verifying the correct help is displayed. For more detail see Online Help Generation. ΓòÉΓòÉΓòÉ 2.5. Project File Selection ΓòÉΓòÉΓòÉ If you select a project file (using 'File Select Project') you will see file icons below the main editing window. You can select any file in the project by clicking on the desired file icon. If there are more files in your project than can be shown in the current space available in the window, use the scroll bar at the bottom of the IPF Editor window to scroll the file icons left or right. You can create a project file using the "File Create Project" menu option. Using projects greatly facilitates generation of online documents and applicaton help. ΓòÉΓòÉΓòÉ 2.6. Source File Size Limitations ΓòÉΓòÉΓòÉ There is a 60,000 byte limit to each source file that may be edited in the IPF Editor. You can create larger documents by using the project option and creating multiple source files (usually one per chapter/section). The IPF Editor limits you to 60,000 bytes when loading or importing files so that you will never exceed the 64K limit on a source file imposed by the IBM IPF Compiler. ΓòÉΓòÉΓòÉ 3. Generating Online Document Files ΓòÉΓòÉΓòÉ The IPF Editor makes creating online documents very simple. You can create basic online documents by just typing in the text, creating a few panel headers, and compiling the file. Larger documents can also be written by creating a project and building panels, hypertext/graphics links, indices, etc. To create on online document perform the following steps: o Enter all text that you wish to include in your document, or import text from a word processor. Create panels as you enter the text or go back and insert panel headers if you imported text. o Mark the document using the standard IPF commands available in the IPF Editor or enter them manually if they are available in the IPF Guide but not directly supported by the IPF Editor. o Create a project by selecting the files to include in your document using the "Create Project." All files must be in the same directory. Use the "Compile Project" option to generate your online document. If any errors are detected double click with the left mouse button on the error shown in the "Compiler Results" window. Fix the error, then compile again until no errors are detected. o Once all errors are corrected test your online document using the "Compiler Test Document" option. o When the document is correct use the "Application Generate Auto-hypertext/graphics link" menu to create hypertext/graphics links automatically for all panel headers in your document. Note: Be sure to sort the files in the order you want to see their respective panel headers show up in the file's table of contents. Generally this isn't a consideration for online help projects but it is very important for online documents. ΓòÉΓòÉΓòÉ 3.1. Creating Online Documentation Panels ΓòÉΓòÉΓòÉ Creating panels can be done in several different ways. You can create panels that have tag resource identifiers, tag names, and/or tag ID's. Which method you use often is based on what type of document you are creating and what information you have when you are creating the panel. When you are creating Online Document panels you do not need to include a tag res, name, or ID value unless you wish to hyperlink some text to the panel. If you want to allow hyperlinking to the panel you are creating you will need to supply a tag res code. You can force the requirement of tag res codes by setting the "Option Require Tag Res" menu option on. Follow these steps to create a panel (including it's panel header): o Enter a title for the panel (A maximum of 32 characters is allowed). o On the following line use the :p. (paragraph) tag by pressing <ALT>-<P>. Then enter the text you want to place in this panel. You can place as many paragraphs, tables, pictures, or other tags as you want into the panel. o Now mark (highlight) the panel's title and select the panel header level you wish to create. Panel headers 1 through 4 are "hyperlinkable" from hypertext/graphics tags. o Enter a tag res code (if you have that option enabled). You can use the default value supplied (which will automatically be incremented each time you create a panel definition). ΓòÉΓòÉΓòÉ 4. Generating Application Online Help Files ΓòÉΓòÉΓòÉ Creating an online help file requires you to correctly tag all panel headers, compile the IPF files (creating a .HLP file), and add resource statements and C function calls to your application. Generating the resource, C source, and include files needed to add online help to your C application is easily accomplished using the "Application Create Help Resource Tables" option. It prompts you to select the source resource and include files, decide on names for the output files. When you have completed your selections, it generates your resource help table file, include file, and C source files. Note: You must also have a 32 bit C Compiler such IBM's C Set/2, C Set ++ and the resource compiler included with the IBM OS/2 2.x Toolkit. ΓòÉΓòÉΓòÉ 4.1. Creating Online Help File Panels ΓòÉΓòÉΓòÉ Each panel in an online help file must have a panel header. The panel header is created using the panel header menu command. There are six level's of panel headers, but only the top four (1-4) are supported by the hypertext/graphics linking commands. Each panel header in an online help file requires a tag resource number. You must enable the "Options Require Tag Res" menu option to force this resource number generation. You may also wish to generate tag names for each panel. This makes it easier to keep track of panel names when creating hypertext/graphics links and other operations performed on panel headers. Each panel's tag resource number must match the resource identifier for the menu item, dialog item, etc. in your application. Panel definition is made much easier by using the "Application Load definition include file" option. This scans the your application's include files, searching for "#defines". Once the files have been read, every time you create a new panel header (the title of the panel) a list of #defines will be presented. This permits you to select the tag res number that will be set to the resource ID number from the #define definition. If you've turned on the tag name option the #define label will automatically be used to create a "PANEL_<label>" tag name for the panel header. Then insert the ":p." (paragraph, with <ALT>-<P>) command on the line immediately following the panel header line and begin typing the description of the applications menu, menu item, dialog, or dialog item. Note: General Help Creation You must define a main panel header and text to enable the general help (the help you get by just pressing F1 with no menu or dialog item selected). This very is easily done by using the automatically defined PANEL_MAIN for the general information panel of your online help. To automatically generate this panel, you must first have turned on the "require tag res" option, ΓòÉΓòÉΓòÉ 4.2. Generating Resource and C Help Files ΓòÉΓòÉΓòÉ To generate the online help file from the IPF files you have entered and tagged you will need to perform the following steps: When you select the "Application Create Help Resource Files" option for the first time in a project the IPF Editor will require that you fill out the name of an include file to use as the basis for generating panel definitions (if you haven't already selected one using the "Application Load Definition Include File (typically this is the include file containing your C #define statements used when you defined your menus and dialogs). You will also need to specify the resource file to scan containing the menu and dialog items for which help is being generated (you can specify the primary resource file which contains "rcinclude" statements to include other resource files). You will also need to determine the file names for the files the IPF Editor is going to create for you. You will need to specify names for the following: - Panel Include File This is the file that will contain all of the #define's required to compile the help resource tables created by the IPF Editor. This should not be the same as any of the include files your application already uses since this procedure will overwrite whatever file name you specify here. - Help Resource File This is the resource file (.RC) that will be created by the IPF Editor. It will create the required help resource statements to support the online help in your application. - C Source File This is the C Source file that will contain the standard C functions your application will call to completely enable the online help. This file should not be the same as any of the C files used for creation of your application since the IPF Editor will overwrite this every time this option is selected. The IPF Editor will now attempt to scan the main resource files for your application. It will read the menu, dialog, and dialog control statements and extract the definition labels for each control. If you are building help for a large project you'll probably want to create a separate directory and copy all of the resource files and include files from each module into it. The IPF Editor will ask you for the application resource ID value (the value assigned to the applications menu, accelerator table, or icon statements in the resource file) if it is unable to find a MENU table to extract it from in the first resource file scanned. Just select the appropriate ID value from the list displayed and that value will be used to create the help resource tables. ΓòÉΓòÉΓòÉ 4.3. C Functions Created ΓòÉΓòÉΓòÉ The IPF Editor creates the following C functions to help you add online help to your applications: o HelpInit Call this after you have created your main window for your application. This will activate the help system with your applications help files. o HelpDestroyInstance This will remove the help system and should be called before you exit your program. If you do not call this before exiting OS/2 will automatically deassociate the help instance from your application (since your application no longer exists). o HelpProcessMessages Call this from your main window function for the following messages: - WM_ACTIVATE - WM_INITMENU - WM_COMMAND - HM_ERROR - HM_GENERAL_HELP_UNDEFINED - HM_HELPSUBITEM_NOT_FOUND The following table shows the functions generated, their arguments, and their purpose: ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöéFunction ΓöéDescription ΓöéArguments Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéHelpInit ΓöéThis intiializes the helpΓöéHWND hwndFrame - Owner ofΓöé Γöé Γöésystem and sets the help Γöéhelp instance. Γöé Γöé Γöéinstance to your Γöé Γöé Γöé Γöéapplication help Γöé Γöé Γöé Γöédocument. Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéHelpDestroyInstance ΓöéThis removes the help ΓöéNo Arguments. Γöé Γöé Γöéinstance. This allows Γöé Γöé Γöé Γöéyou to set a new help Γöé Γöé Γöé Γöéinstance or you may call Γöé Γöé Γöé Γöéthis before your programΓöé Γöé Γöé Γöéexits. Γöé Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéHelpProcessMessages ΓöéThis will process ΓöéHWND hwnd, USHORT msg, Γöé Γöé ΓöéWM_ACTIVATE, WM_INITMENU,ΓöéMPARAM mp1, MPARAM mp2 - Γöé Γöé Γöéand WM_COMMAND messages ΓöéStandard window procedureΓöé Γöé Γöéand process help related Γöéarguments. Γöé Γöé Γöéportions of these Γöé Γöé Γöé Γöémessages. Γöé Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Generally you should call the HelpInit after you have created your application's main frame window. You can call the HelpDestroyInstance before you destroy the frame window. The HelpProcessMessages should be called during your main window's message processing for the specific messages listed above. ΓòÉΓòÉΓòÉ 4.3.1. C Function Usage Example ΓòÉΓòÉΓòÉ The following shows typical usage of the C functions created by the IPF Editor. Your application can use these to initialize and uninitialize the help manager: int main(int argc, char *argv[], char *envp[]) { HAB hab; // Anchor block HMQ hmq; // Message Queue handle PCHAR pszClass = "IPFEDEMO"; // Class name ULONG flFrameFlags = // Frame definition FCF_SIZEBORDER | FCF_MENU | FCF_ICON | FCF_TITLEBAR | FCF_SHELLPOSITION | FCF_TASKLIST | FCF_MINMAX; QMSG qmsg; // Message queue contents hab = WinInitialize( 0 ); hmq = WinCreateMsgQueue( hab, 0 ); // Register our window class WinRegisterClass( hab, pszClass, (PFNWP) IPFEDemoWndProc, CS_SIZEREDRAW, 0 ); // Create standard window hwndFrame = WinCreateStdWindow( HWND_DESKTOP, WS_VISIBLE, &flFrameFlags, pszClass, "IPF Editor Demo C Program", WS_VISIBLE, 0L, IDD_IPFEDEMO, &hwndClient ); // Initialize help system HelpInit( hwndFrame ); // Loop until terminated while( WinGetMsg( hab, &qmsg, 0L, 0, 0 ) ) WinDispatchMsg( hab, &qmsg ); // Terminate help system HelpDestroyInstance(); // Kill window WinDestroyWindow( hwndFrame ); // Destroy message queue WinDestroyMsgQueue( hmq ); // Kill handle to anchor block WinTerminate( hab ); // Exit with error code of zero exit( 0 ); } Use the HelpProcessMessages() as shown in the following code fragment: MRESULT EXPENTRY IPFEDemoWndProc( HWND hwnd, USHORT msg, MPARAM mp1, MPARAM mp2 ) { switch( msg ) { // Process messages help needs to be aware of case WM_ACTIVATE: case WM_INITMENU: return HelpProcessMessages( hwnd, msg, mp1, mp2 ); case HM_ERROR: DosBeep( 500, 250 ); DosBeep( 500, 250 ); return HelpProcessMessages( hwnd, msg, mp1, mp2 ); case HM_HELPSUBITEM_NOT_FOUND: DosBeep( 1000, 100 ); return HelpProcessMessages( hwnd, msg, mp1, mp2 ); case WM_HELP: DosBeep( 100, 100 ); return HelpProcessMessages( hwnd, msg, mp1, mp2 ); // Process command messages case WM_COMMAND: // Make sure help get's chance to see WM_COMMAND message HelpProcessMessages( hwnd, msg, mp1, mp2 ); . . . } It's important to note that your application probably would not want to return the result of the help access when processing the WM_COMMAND message since it will probably want to handle the specific WM_COMMAND message and return it's result instead of the generic result used by the help manager. ΓòÉΓòÉΓòÉ 4.4. General rules for using the IPF Editor ΓòÉΓòÉΓòÉ General Rules for easily creating help for your applications: o Always create all dialog boxes using individual resource ID values. Don't create two or more dialog boxes that have controls with the same ID's in them. Also avoid creating controls or dialogs with resource ID's which are the same as Menu ID's. o Adding Headers If you wish to add headers to a project that has already been loaded always save the file, then reload the project before using the Application Generate Resource Option. This allows the IPF Editor to accurately scan all files that have been modified before building the help related files. o Scanning Include Files Be sure to scan the include files before trying to add headers as this will automatically create header panel ID's for you. If you try to generate a header and no panel ID's are are available, you have not yet scanned an include file. o Help Menu Items The following help menu items are automatically generated in the C source file: - IDM_HELP_USING - IDM_HELP_INDEX - IDM_HELP_CONTENTS - IDM_HELP_GENERAL The IPF Editor assumes that you have defined each of the above menu items; it uses them without defining them. Code to process these messages is automatically generated; to take advantage of this code you must define them in an include file. You must also create the appropriate menu item statements in your applications menu resource statement. If you do not want to handle these in your application, comment them out of the C source file generated. This is what a typical C include file would contain to define the needed menu items. #define IDM_HELP 150 #define IDM_HELP_USING 155 #define IDM_HELP_INDEX 160 #define IDM_HELP_CONTENTS 165 #define IDM_HELP_GENERAL 170 This is what a typical resource file would contain to generate a help sub-menu. SUBMENU "~Help", IDM_HELP { MENUITEM "Help ~index", IDM_HELP_INDEX MENUITEM "~General help", IDM_HELP_GENERAL MENUITEM "~Using help", IDM_HELP_USING MENUITEM "Help ~contents", IDM_HELP_CONTENTS } Warning: You must define one panel as PANEL_MAIN so that the application can correctly initialize the help manager. The PANEL_MAIN is the general help displayed when the user presses F1 with no menu or dialog selected. ΓòÉΓòÉΓòÉ 4.5. Application Create Help Resource Tables Limitations ΓòÉΓòÉΓòÉ The following limitations exist (per project) when creating application help resource files: o 1 Primary Menu The first MENU statement found is the one used. Any following MENU statements are ignored. Generally, applications have a menu used in the menu bar, and some may have a pop-up menu containing a sub-set of the regular menu. The IPF Editor will generate help resource files that will provide help for both menus automatically. o 256 Menu Items o 4096 Panel Definition Names from Include Files Include files contain base ID code and definition and are automatically converted to PANEL_xxxx statements as required by your tagged document(s). o 128 Dialog boxes o 32 Controls per dialog box o 32 Include Files (containing definitions for dialog and menu items) ΓòÉΓòÉΓòÉ 5. Compiling Projects and Files ΓòÉΓòÉΓòÉ The IPF Editor provides you with an easy to use interface to your IPF Compiler (part of the OS/2 2.x Toolkit). You can select the type of file to create (online help or online document), what level of file errors to look for, whether to generate a cross reference list, and what the name should be for the file being created. Of course if you are using the Project capabilities of the IPF Editor most of these fields will be filled out for you automatically. The only choice you will have to make is whether or not to display the results in the "Result Window." ΓòÉΓòÉΓòÉ 5.1. Output Files ΓòÉΓòÉΓòÉ The IPF Compiler will generate either a .HLP or a .INF file based on the type of file being produced. If you are generating an "online document" for use with the OS/2 VIEW.EXE program you will produce a .INF file. If you are creating a help file you will create a .HLP file. Note: If you are creating online help files you must have created the help resource tables required for building into your application. See "Generating Application Online Help Files" for more details. ΓòÉΓòÉΓòÉ 5.2. IPFC Environment Variable ΓòÉΓòÉΓòÉ The IPF Compiler requires an IPFC environment variable value to operate correctly. It points to the IPFC directory in the OS/2 2.x Toolkit. This is filled in automatically by the IPF Editor if you have the IPFC environment variable defined in your CONFIG.SYS. If you don't have it predefined you will need to fill this value with the path to the \TOOLKT20\IPFC directory. ΓòÉΓòÉΓòÉ 5.3. IPF Compiler Path ΓòÉΓòÉΓòÉ The IPF Editor needs to know where to locate your IPF Compiler. If the IPFC compiler is in your OS/2 PATH, you will not need to specify the path implicitly. If it isn't, you will need to use enter the location of your IPFC compiler. Note: You will only need to do this once since the IPF Editor remembers where you last specified the location of your IPF Compiler. ΓòÉΓòÉΓòÉ 5.4. IPF Compiler Results Window ΓòÉΓòÉΓòÉ The IPF Compiler Results window shows you the results of your last IPF Compiler compile. You may scroll through the list of messages shown in it. If you see an error message (a message that starts with "<filename:n> nnn") you may double click on it and you will be taken directly to the error in that file and the location in that file. The following shows how to read an error message: <IPFEHHLP.IPF:1> 101: Invalid Document Body. The file and the line number containing the error is shown in the opening brackets. The next number (in the example 101) shows both the severity (indicated by the one-hundred level number) and the error message index (the 01 portion). If you look up error 101 you will see that it is an "Invalid Document Body" message. ΓòÉΓòÉΓòÉ 6. Generating Hypertext Links ΓòÉΓòÉΓòÉ To generate hypertext/graphics links you can either manually mark and select panel headers to link text to or use the "Application Generate Auto-Hypertext/graphics links" menu option. This will scan either the current file or the current project (or any files in the current project you select) for any words that match panel headings defined in any file in the current project. The IPF Editor inserts the appropriate hyperlink command automatically. Matches are based on the heading name matching exactly (not counting case) text in the file. If the text being linked ends with an 'S' (as in a plural version of the word) the 'S' will be included in the hypertext link. This function can take from several seconds to several hours depending on the size of your project and the speed of your system. However, all activity takes place in the background so you can use your system for other operations while the auto hyperlinking is taking place. ΓòÉΓòÉΓòÉ 7. Sorting Panel Headers ΓòÉΓòÉΓòÉ In order to sort panel headers in your project you will need to be sure that each individual IPF file is sorted in the manner you want (i.e. the first panel header in the file is the file you want to precede all other panel headers in that file). If you wish to rearrange the panel headers in several different files you will need to edit the base IPF file created by the IPF Editor. This file contains several "┬╖imbed" statements, one per IPF file in your project. By changing the order of these statements you can alter the order of the IPF file's panel's in the document's table of contents. ΓòÉΓòÉΓòÉ 8. IPF Commands Supported ΓòÉΓòÉΓòÉ The "IPF Commands" menu lets you select different tags to add to your documentation. You can access most of these menu options from the pop-up menu by pressing the right mouse button while the pointer is over the document editing window or the most common commands from the "graphical menu" located at the right side of the IPF Editor window. The IPF Editor provides a majority of the IPF tag commands you will require in everyday use. You may, of course, use any other standard IPF tag described in the IPF documentation even if it isn't supported directly by the IPF Editor. Just type the commands in directly. ΓòÉΓòÉΓòÉ 8.1. Special IPF Commands Menu ΓòÉΓòÉΓòÉ This menu lets you access tags that are less commonly used. You can mark the document title, body of the document, hypertext/graphics links, etc. Most of the commands you would commonly use in this menu can be accessed via the pop-up menu or the graphical menu but are here to support whichever method you find the most convenient. ΓòÉΓòÉΓòÉ 8.2. Title Tag Information ΓòÉΓòÉΓòÉ This tag lets you specify the title of the document you are editing. This tag is only valid for online documents and shouldn't be used for online help windows. The maximum length the title can be is 47 characters, including spaces and blanks. Tagging Information Insert this tag on a blank line following the :userdoc. tag. The following shows the proper usage of the :title. tag: :userdoc. :title.Using the Title Tag :h1 res=100.A Panel Heading :p.This is an example. :euserdoc. If you were to compile this example it would generate an online document and place "Using the Title Tag" in the title line of the main window. Note: If you are using the project option, and creating an automatic base file, you never need to use this tag as it is automatically placed in the base IPF file when you create the project. ΓòÉΓòÉΓòÉ 8.3. User Documentation Tags Information ΓòÉΓòÉΓòÉ These tags (:userdoc. and :euserdoc.) are placed at the beginning and ending of your document. These allow the IPFC compiler to correctly determine the complete contents of your document. The following shows a very brief sample document that uses the user document tags: :userdoc. :body. ┬╖* This is a comment in an empty documentation file. :euserdoc. Tagging Information Place the :userdoc. before any other statements in your document file and the :euserdoc. after all the statements in your document file. Both statements must reside in the same file and you must not use these statements more than once in the same document. Note: If you are using the project option, and creating an automatic base file, you never need to use this tag as it is automatically placed in the base IPF file. ΓòÉΓòÉΓòÉ 8.4. Body Tag Information ΓòÉΓòÉΓòÉ This (:body.) marks the beginning of the text body for your IPF documentation file. This must be placed after the :userdoc. tag and normally also after the :title. tag. This must be placed before any heading tags or commands to imbed other IPF files into your document. Tagging Information Place this after the :userdoc. and :title. statements but before any heading or imbed statements. :userdoc. :body. :euserdoc. Note: If you are using the project option, and creating an automatic base file, you never need to use this tag as it is automatically placed in the base IPF file. ΓòÉΓòÉΓòÉ 8.5. Comment Tag Information ΓòÉΓòÉΓòÉ This tag (┬╖*) marks the rest of the current line to the right of it as a comment. It is ignored by the IPFC compiler. You can use this tag to help keep track of revisions to the documentation and to add comments describing links to other documents, etc. Tagging Information Place the cursor anywhere in your document and then select the comment tag menu item. The tag will be inserted at that location and everything to the right of the tag will be considered a comment and not show up in your output document. ┬╖* This is a comment. ┬╖* This is a second comment. ΓòÉΓòÉΓòÉ 8.6. Imbed File Tag Information ΓòÉΓòÉΓòÉ The imbed file tag (┬╖im filename) lets you imbed (include or merge when the document is compiled) a specific IPF document file into the current document. Usually this command is used in a base file to include different chapters (each located in a different file) into a single online document. This online help was split up into separate files, one for each submenu and one for each dialog box to make maintenance easier. Tagging Information To use this option place the cursor on a blank line in your document, select this option, then select the IPF document file to imbed. :userdoc. :body. ┬╖im chapter1.ipf ┬╖im chapter2.ipf ┬╖im chapter3.ipf :euserdoc. Note: If you are using the project option, and creating an automatic base file, you never need to use this tag as it is automatically placed in the base IPF file. If you wish to add a new file to the project use the "File New" command to create a new file, then paste the new text into it. ΓòÉΓòÉΓòÉ 8.7. Setup Button Controls ΓòÉΓòÉΓòÉ This option lets you define what buttons are displayed below your help page/online document in either the Help Window or View program. You can select to show the Previous, Search, Next, Index, etc. buttons in your document. The default buttons shown (if you don't specify this command) are: o Online Documents - Previous - Search - Print - Index - Contents - Back - Forward - Tutorial (but only if a tutorial is available). o Help windows - Previous - Search - Print - Index - Tutorial (but only if a tutorial is available). ΓòÉΓòÉΓòÉ 8.7.1. Push-Button Control Selection ΓòÉΓòÉΓòÉ This dialog allows you to select which push-buttons you want activated in your help document. ΓòÉΓòÉΓòÉ 8.7.2. Search ΓòÉΓòÉΓòÉ Selecting this will cause the "Search" push button to be displayed at the bottom of the document window. ΓòÉΓòÉΓòÉ 8.7.3. Print ΓòÉΓòÉΓòÉ Selecting this will cause the "Print" push button to be displayed at the bottom of the document window. ΓòÉΓòÉΓòÉ 8.7.4. Index ΓòÉΓòÉΓòÉ Selecting this will cause the "Index" push button to be displayed at the bottom of the document window. ΓòÉΓòÉΓòÉ 8.7.5. Contents ΓòÉΓòÉΓòÉ Selecting this will cause the "Contents" push button to be displayed at the bottom of the document window. ΓòÉΓòÉΓòÉ 8.7.6. Esc ΓòÉΓòÉΓòÉ Selecting this will cause the "Esc" push button to be displayed at the bottom of the document window. ΓòÉΓòÉΓòÉ 8.7.7. Back ΓòÉΓòÉΓòÉ Selecting this will cause the "Back" push button to be displayed at the bottom of the document window. ΓòÉΓòÉΓòÉ 8.7.8. Forward ΓòÉΓòÉΓòÉ Selecting this will cause the "Forward" push button to be displayed at the bottom of the document window. ΓòÉΓòÉΓòÉ 8.7.9. Page ΓòÉΓòÉΓòÉ This will assign the control settings to either the current panel heading only. ΓòÉΓòÉΓòÉ 8.7.10. Coverpage ΓòÉΓòÉΓòÉ This will assign the control settings to the main window (unless over-ridden by another control button setup for a specific page (panel heading). ΓòÉΓòÉΓòÉ 8.7.11. Res Code Identifier ΓòÉΓòÉΓòÉ Selecting this will let you define a res. code for push button control ΓòÉΓòÉΓòÉ 8.7.12. Name Identifier ΓòÉΓòÉΓòÉ Selecting htis will let you define a name indentifier for the push button control ΓòÉΓòÉΓòÉ 8.8. Paragraph Tag Information ΓòÉΓòÉΓòÉ The paragraph tag (:p.) is one of the most common tags to use. It marks the start of a paragraph and the paragraph continues until another tag, marking either a new paragraph or some other sectional tag (such as lists or sub-sections), is placed. Tagging Information The paragraph tag can most easily be placed by positioning the cursor at the beginning of a paragraph, pressing the right button, and selecting the currently highlighted paragraph menu option. (To speed tagging, you may wish to just place the cursor anywhere on the first word in the paragraph, double click with the left button, then press the right button to insert the tag). The following shows the typical use of the paragraph tag: :h1 res=100.File Open Help :p.This menu option allows you to open files. Note: You may also generate the paragraph tag by pressing ALT-P. ΓòÉΓòÉΓòÉ 8.9. Panel Header Tag Information ΓòÉΓòÉΓòÉ The panel header tags provide you with the ability to create separate panels for different parts of your documentation. Generally, each heading in your online documentation has a panel header tag. Panel header tags are also used to allow hyper-text and hyper-graphic links to be made to different portions of the document. The IPF Editor currently supports up to 32,000 panel header tags in a single project. There are six levels of panel headers available. Generally each panel header level represents a different level in the table of contents. Level one headers always are displayed in the table of contents, while header two are not shown unless the level headers are expanded. In this online help document, the sub-menus are all level one headers, while the menu items themselves are level two menu items. Some reference panels are level three or deeper headers. It is important to remember that only panel header levels 1 through 3 may be linked to using hypertext/graphics links. You may have chosen to require either panel header res codes, panel header tag names, or header tag ID's. If you choose panel header tag names, and have loaded a C Language Include file, you will see a list of possible definitions to use for your res codes and name codes. This option is only available in the professional (registered) version of the IPF Editor. You may also use the auto-increment feature and enter your own res codes to build a document without an external definition list. If you are using the pre-defined definitions the auto-increment feature is not used on the selected res number. Panel header name codes are usually generated from the C Language Include file when generating online help files. Otherwise you may type in your own name for the panel being generated. Generally, the panel name should be 32 characters or less, and have some relevance to the panel being marked. Tagging Information To create a panel header mark the text you want to use for the panel header title using your mouse to select the desired text. Then select the header-level you desire from the menu. Then choose the pre-defined definition or enter in the res number, panel name, and tag ID as required. Some headers may not require res, name, or tag values if they are merely part of a document and won't be hyper-linked to. Panels that will not be hyperlinked to do not requires res codes. The following shows a typical panel header definition: :h1 res=100.Panel Name :p.This is a panel with a panel header at level 1. ΓòÉΓòÉΓòÉ 8.9.1. Panel Header 1 Information ΓòÉΓòÉΓòÉ This generates a first level panel header that will show up in the documents table of contents. Note: This panel header is a linkable panel header (this means that hypertext/graphics links may be made to this panel header). ΓòÉΓòÉΓòÉ 8.9.2. Panel Header 2 Information ΓòÉΓòÉΓòÉ This generates a second level panel header that will show up in the documents table of contents. Note: This panel header is a linkable panel header (this means that hypertext/graphics links may be made to this panel header). ΓòÉΓòÉΓòÉ 8.9.3. Panel Header 3 Information ΓòÉΓòÉΓòÉ This generates a third level header that will show up in the documents table of contents. Note: This panel header is a linkable panel header (this means that hypertext/graphics links may be made to this panel header). ΓòÉΓòÉΓòÉ 8.9.4. Panel Header 4 Information ΓòÉΓòÉΓòÉ This generates a fourth level panel header that will show up in the documents table of contents. Note: This level panel header may not be linked via hypertext/graphics links. ΓòÉΓòÉΓòÉ 8.9.5. Panel Header 5 Information ΓòÉΓòÉΓòÉ This generates a fifth level panel header that will show up in the documents table of contents. Note: This level panel header may not be linked via hypertext/graphics links. ΓòÉΓòÉΓòÉ 8.9.6. Panel Header 6 Information ΓòÉΓòÉΓòÉ This generates a sixth level panel header that will show up in the documents table of contents. Note: This level panel header may not be linked via hypertext/graphics links. ΓòÉΓòÉΓòÉ 8.10. Highlighting Tag Information ΓòÉΓòÉΓòÉ Use these options to select different appearances for selected text. You can choose any of the following text formats: o This is an example of :hp1. o This is an example of :hp2. o This is an example of :hp3. o This is an example of :hp4. o This is an example of :hp5. o This is an example of :hp6. o This is an example of :hp7. o This is an example of :hp8. o This is an example of :hp9. Tagging Information Place the cursor at the beginning of the text to be marked and select it. Then choose the desired highlighting method. A :hp1. and :eh1. (or whatever method you chose from 1 to 9) will be inserted into the text. ΓòÉΓòÉΓòÉ 8.10.1. Highlighting Italics Information ΓòÉΓòÉΓòÉ This is an example of :hp1. Italics text. See Highlighting Tag Information for usage details. ΓòÉΓòÉΓòÉ 8.10.2. Highlighting Bold Information ΓòÉΓòÉΓòÉ This is an example of :hp2. bold text. See Highlighting Tag Information for usage details. ΓòÉΓòÉΓòÉ 8.10.3. Highlighting Bold Italics Information ΓòÉΓòÉΓòÉ This is an example of :hp3. bold italics. See Highlighting Tag Information for usage details. ΓòÉΓòÉΓòÉ 8.10.4. Highlighting Blue Information ΓòÉΓòÉΓòÉ This is an example of :hp4. blue text. See Highlighting Tag Information for usage details. ΓòÉΓòÉΓòÉ 8.10.5. Highlighting Underlined Information ΓòÉΓòÉΓòÉ This is an example of :hp5. underlined text. See Highlighting Tag Information for usage details. ΓòÉΓòÉΓòÉ 8.10.6. Highlighting Underlined Italics Information ΓòÉΓòÉΓòÉ This is an example of :hp6. underlined italics text. See Highlighting Tag Information for usage details. ΓòÉΓòÉΓòÉ 8.10.7. Highlighting Underlined Blue Information ΓòÉΓòÉΓòÉ This is an example of :hp7. underlined blue text. See Highlighting Tag Information for usage details. ΓòÉΓòÉΓòÉ 8.10.8. Highlighting Red Information ΓòÉΓòÉΓòÉ This is an example of :hp8. red text. See Highlighting Tag Information for usage details. ΓòÉΓòÉΓòÉ 8.10.9. Highlighting Magenta Information ΓòÉΓòÉΓòÉ This is an example of :hp9. magenta text. See Highlighting Tag Information for usage details. ΓòÉΓòÉΓòÉ 8.11. Figures/Artwork Tag Information ΓòÉΓòÉΓòÉ This menu provides you with the ability to add both figures (and captions), bitmap graphics, and character graphics to your document. ΓòÉΓòÉΓòÉ 8.11.1. Figure Tag Information ΓòÉΓòÉΓòÉ The figure tags allow you to mark text as a figure that will be displayed in a format exactly as entered. The tags that surround figures are :fig. and :efig. Tagging Information Mark the selected text to be identified as a figure using your mouse then select the Figure Tag menu item. The following shows the markings for a text figure: :fig. A B C D E 1 $100.00 $ -45.00 This spreadsheet shows 2 $200.00 $ 131.15 text captured from my spreadsheet 3 $150.00 $ 22.20 program. 4 @SUM(A1..A3) @SUM(B1..B3) 5 :efig. This will look like the following in your document: A B C D E 1 $100.00 $ -45.00 This spreadsheet shows 2 $200.00 $ 131.15 text captured from my spreadsheet 3 $150.00 $ 22.20 program. 4 @SUM(A1..A3) @SUM(B1..B3) 5 ΓòÉΓòÉΓòÉ 8.11.2. Figure Caption Tag Information ΓòÉΓòÉΓòÉ This (:figcap.) allows you to add a title to figures. Tagging Information The pointer is placed between the :fig. and :efig. statements and then select this option. ΓòÉΓòÉΓòÉ 8.11.3. Character Graphics Tag Information ΓòÉΓòÉΓòÉ These tags (:cgraphic. and :ecgraphic.) identify marked text as a character graphic that will be displayed in the monospace system font. A blank line is inserted before and after the graphic. Tagging Information Mark the graphic text and then select the the Character Graphics menu item. Note: This can be used to display the character graphics symbols that consist of the upper 128 bytes in the ASCII table. ΓòÉΓòÉΓòÉ 8.11.4. Artwork Tag Information ΓòÉΓòÉΓòÉ This tag (:artwork filename.) allows you to include bitmaps and metafiles into your document. Tagging Information Place the pointer where you wish to insert the bitmap and then select the Artwork menu item or select the graphics menu item. Select the bitmap to insert from the file list, then determine alignment for the bitmap (either left, center, right, in-line, or no alignment). The following shows a typical bitmap displayed: The above bitmap was loaded using the following tag: :artwork name='IPFEDIT.BMP' align=left. You may wish to edit the path to the bitmap so that it doesn't include the drive label if you plan on working on the document on several different computers (unless each computer has the same drive/directory structure). ΓòÉΓòÉΓòÉ 8.11.4.1. Artwork Setup ΓòÉΓòÉΓòÉ The Artwork setup page allows you to select artwork (either bitmaps or metafiles) for inclusion in your online document. ΓòÉΓòÉΓòÉ 8.11.4.2. Bitmap/Metafile Name ΓòÉΓòÉΓòÉ This field contains the name of the bitmap or metafile to include in your document. Normally this field is filled in when you press the Select Graphic button but you may manually enter any bitmap or metafile name here, instead. ΓòÉΓòÉΓòÉ 8.11.4.3. Select Graphic ΓòÉΓòÉΓòÉ This will bring up a file dialog that will allow you to select a bitmap or metafile for inclusion into your document. ΓòÉΓòÉΓòÉ 8.11.4.4. Preview ΓòÉΓòÉΓòÉ This will display the selected bitmap in a window so that you may verify you have chosen the correct art. ΓòÉΓòÉΓòÉ 8.11.4.5. Link Artwork ΓòÉΓòÉΓòÉ This option is not currently supported, sorry. Future versions will support this option. Please use the hypertext/graphics link to link artwork. ΓòÉΓòÉΓòÉ 8.11.4.6. Alignment Left ΓòÉΓòÉΓòÉ This will align the artwork at the left portion of the display. ΓòÉΓòÉΓòÉ 8.11.4.7. Alignment Center ΓòÉΓòÉΓòÉ This will align the artwork in the center part of the display. ΓòÉΓòÉΓòÉ 8.11.4.8. Alignment Right ΓòÉΓòÉΓòÉ This will align the artwork at the right portion of the display. ΓòÉΓòÉΓòÉ 8.11.4.9. Alignment In-Line ΓòÉΓòÉΓòÉ This will place the artwork in the middle of the line, as shown below: The symbol, , is in the middle of this line. ΓòÉΓòÉΓòÉ 8.11.4.10. Alignment Fit ΓòÉΓòÉΓòÉ This will fit the artwork into the current display page (compressing or exanding it as necessary). ΓòÉΓòÉΓòÉ 8.11.4.11. Alignment None ΓòÉΓòÉΓòÉ This will place the artwork at the current location and not adjust its size or position at all. ΓòÉΓòÉΓòÉ 8.11.4.12. Artwork Setup Save ΓòÉΓòÉΓòÉ This will save your select artwork and insert it into your document. ΓòÉΓòÉΓòÉ 8.12. Foreground Color Tag ΓòÉΓòÉΓòÉ These tags (:fc=color.) lets you change the documents output color. The color remains set to this until the next panel header is encountered or until a new :fc=color. command is encountered. Tagging Information Place the pointer at the location where you wish to start changing the color and then select the foreground color command from the color list. ΓòÉΓòÉΓòÉ 8.12.1. fc=default ΓòÉΓòÉΓòÉ This sets the current foreground text color to the default (Whatever the user has selected for the default help information text color). The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.12.2. fc=blue Information ΓòÉΓòÉΓòÉ This sets the current foreground text color to blue. The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.12.3. fc=cyan Information ΓòÉΓòÉΓòÉ This sets the current foreground text color to cyan. The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.12.4. fc=green Information ΓòÉΓòÉΓòÉ This sets the current foreground text color to green. The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.12.5. fc=neutral Information ΓòÉΓòÉΓòÉ This sets the current foreground text color to neutral (this is the same as the help manager background color). The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.12.6. fc=yellow Information ΓòÉΓòÉΓòÉ This sets the current foreground text color to yellow. The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.13. Background Color Tag Information ΓòÉΓòÉΓòÉ These tags (:bc=color.) lets you change the documents output background color. The color remains set to this until the next panel is encountered or until a new :bc=color. command is encountered. Tagging Information Place the pointer at the location where you wish to start changing the text background color and then select the background color command from the color list. ΓòÉΓòÉΓòÉ 8.13.1. bc=default Information ΓòÉΓòÉΓòÉ This sets the current background text color to the default (Whatever the user has selected for the default help information text color). The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.13.2. bc=blue Information ΓòÉΓòÉΓòÉ This sets the current background text color to blue. The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.13.3. bc=cyan Information ΓòÉΓòÉΓòÉ This sets the current background text color to cyan. The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.13.4. bc=green Information ΓòÉΓòÉΓòÉ This sets the current background text color to green. The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.13.5. bc=neutral Information ΓòÉΓòÉΓòÉ This sets the current background text color to neutral (this is the same as the help manager background color). The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.13.6. bc=yellow Information ΓòÉΓòÉΓòÉ This sets the current foreground text color to yellow. The color stays in effect until a new color is selected or until the panel description ends. ΓòÉΓòÉΓòÉ 8.14. Sub-Sections Menu Information ΓòÉΓòÉΓòÉ These IPF commands allow you to mark text as notes, note paragraphs, examples, footnotes, warnings, and tables. ΓòÉΓòÉΓòÉ 8.14.1. Caution Information ΓòÉΓòÉΓòÉ The Caution tag allows you to mark a section of text using the caution attribute. Tagging Information Place the pointer before the text to display as a cautionary statement, then select the caution tag. The following shows an example of the Caution tag: :caution.This is an example of the caution tag.:ecaution. which appears as the following in your document: CAUTION: This is an example of the caution tag. Note: You can insert a blank line after the "CAUTION:" text by starting to tag on a blank line above the text you wish to include in your caution tag. ΓòÉΓòÉΓòÉ 8.14.2. Note Information ΓòÉΓòÉΓòÉ The Note tag allows you to add a Note: line into your document. Tagging Information Place the pointer at the beginning of the line to tag as a single line note. Then select the note tag. The following shows an example of the Note tag: :note.This is a note example. which displays as shown below: Note: This is a note example. ΓòÉΓòÉΓòÉ 8.14.3. Note Paragraph Information ΓòÉΓòÉΓòÉ The Note Paragraph tag lets you create a paragraph note to your document. This is different from the line note tag which only marks a single line as a note. Below is an example of a paragraph note tag that contains several lines of text: :nt.The text will wrap around and allow you to place multiple lines of text as needed to complete your note. :ent. which displays as shown below: Note: The text will wrap around and allow you to place multiple lines of text as needed to complete your note. Note: If you only need a single line note try the Note tag. ΓòÉΓòÉΓòÉ 8.14.4. Footnote Information ΓòÉΓòÉΓòÉ Use this tag to add footnotes to your document. Footnotes cause a pop-up window to appear with the text you place in the footnote when the user selects a hyperlink to it. The tag requires that you enter a tag name so that you may use a hyperlink to the footnote. Tagging Information Mark the desired text for the footnote, then select the footnote command or use the menu item. The following is a sample footnote: :fn id=Footnote_sample. This is a footnote. :efn. Select Footnote Sample to display the example footnote. ΓòÉΓòÉΓòÉ 8.14.5. Warning Information ΓòÉΓòÉΓòÉ This will add the Warning statement to your text. Tagging Information Mark the desired text then select the warning tag. The following shows a sample tagging: :warning.This is a warning example.:ewarning. which looks like the following: Warning: This is a warning example. ΓòÉΓòÉΓòÉ 8.14.6. Example Information ΓòÉΓòÉΓòÉ This allows you to mark text as an example. The following shows an example of example tagging: :xmp. This is an example, showing monospaced text and indentation. Indented just like I typed it. :exmp. which displays as follows: This is an example, showing monospaced text and indentation. Indented just like I typed it. Note: The text is changed to monospaced for examples automatically. ΓòÉΓòÉΓòÉ 8.14.7. Table Information ΓòÉΓòÉΓòÉ This lets you create tables, organized by rows and columns. When you are asked to specify the column size you must enter one width for each column separated by spaces. The table below was created using the following tags: :table cols='20 15'. :row. :c┬╖Column # 1, Row #1 :c┬╖Column # 2, Row #1 :row. :c┬╖Column #1, Row # 2 :c┬╖Column #2, Row # 2 :etable. The following shows what the above tagging generates: ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöéColumn # 1, Row #1 ΓöéColumn # 2, RowΓöé Γöé Γöé#1 Γöé Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓöéColumn #1, Row # 2 ΓöéColumn #2, Row Γöé Γöé Γöé# 2 Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ The entire contents of the table was selected then marked using the Sub-Section Table command with the column sizes entered as "20 15" (signifying that the first column is 20 characters wide and the second 15). Then each column and row were marked individually using the Table Row and Table Column commands. ΓòÉΓòÉΓòÉ 8.14.7.1. Table Row Information ΓòÉΓòÉΓòÉ This lets you mark text as the start of a new row in a table. ΓòÉΓòÉΓòÉ 8.14.7.2. Table Column Information ΓòÉΓòÉΓòÉ This lets you mark text as the start of a new column in a table. ΓòÉΓòÉΓòÉ 8.15. List Menu Information ΓòÉΓòÉΓòÉ The list sub-menu allows you to mark a variety of lists in your document. Simple, ordered, unordered, and definition lists may be marked. Each list may also be marked as compact or normal depending on how you wish the list to be displayed. The following lists are supported: o Parameter Lists o Definition Lists o Ordered Lists o Unordered Lists o Simple Lists Tagging Information If you separate each item in your list with a blank line each item will automatically be tagged with a list item for you (:li.). ΓòÉΓòÉΓòÉ 8.15.1. Compact Lists Information ΓòÉΓòÉΓòÉ This attribute allows you to cause a list to be compacted (removes blank lines between list items). The following is a standard unordered list: o 101 Dalmations o Dumbo o Beauty and the Beast o Little Mermaid This is the same list, compacted: o 101 Dalmations o Dumbo o Beauty and the Beast o Little Mermaid Note: You must select the compact option before marking a list since this is a modifier to the standard list commands. ΓòÉΓòÉΓòÉ 8.15.2. Definition Lists Information ΓòÉΓòÉΓòÉ This submenu lets you create definition lists. ΓòÉΓòÉΓòÉ 8.15.2.1. Definition List Information ΓòÉΓòÉΓòÉ The definition list tag allows you to tag selected text as a definition list. A definition list is a list of terms and their meanings. To make use of this you must have text tagged with the term-heading tag and description heading tag, as well as text tagged with the term and description tags. The following shows the tagging for a simple definition table: :dl tsize=20. :dthd.Function Name :ddhd.Purpose :dt.ScreenErase() :dd.Erase the display screen :dt.ScreenWrite() :dd.Write data to screen :edl. which will be displayed as: Function Name Purpose ScreenErase() Erase the display screen ScreenWrite() Write data to screen ΓòÉΓòÉΓòÉ 8.15.2.2. Definition Term Heading ΓòÉΓòÉΓòÉ Use this to mark the heading describing the definition term column. ΓòÉΓòÉΓòÉ 8.15.2.3. Definition Description Heading ΓòÉΓòÉΓòÉ Use this to mark the heading describing the definition description column. ΓòÉΓòÉΓòÉ 8.15.2.4. Definition Term ΓòÉΓòÉΓòÉ This is used to mark the definition term being defined. ΓòÉΓòÉΓòÉ 8.15.2.5. Definition Description ΓòÉΓòÉΓòÉ This is used to mark the definition description associated with the preceding definition term. ΓòÉΓòÉΓòÉ 8.15.3. Parameter List Menu Information ΓòÉΓòÉΓòÉ This submenu provides you with the options to create parameter lists. ΓòÉΓòÉΓòÉ 8.15.3.1. Parameter List Definition ΓòÉΓòÉΓòÉ This lets you create a parameter list. The following shows a simple parameter list tagging: :parml tsize=20. :pt.Parm1 :pd.Description of Parm1 :pt.Parm2 :pd.Description of Parm2 :eparml. which is displayed as follows: Parm1 Description of Parm1 Parm2 Description of Parm2 This was created by placing the parameter term (Parm1 and Parm2) on separate lines with the parameter descriptions on the lines immediately following them. The entire section was then marked as a parameter list. Terms are marked using the Parameter List Term tag and the definitions with the Parameter List Description tag. ΓòÉΓòÉΓòÉ 8.15.3.2. Parameter List Term ΓòÉΓòÉΓòÉ This marks the term that will be defined in the parameter list. ΓòÉΓòÉΓòÉ 8.15.3.3. Parameter List Definition ΓòÉΓòÉΓòÉ This defines the definition of a parameter in a parameter list. ΓòÉΓòÉΓòÉ 8.15.4. Ordered Lists Information ΓòÉΓòÉΓòÉ This creates an ordered list from selected text. The following shows the tagging for an ordered list using the following names: :ol. :li.Zoe :li.Delaine :li.Danika :li.Brent :li.Bill :eol. which displays as follows: 1. Zoe 2. Delaine 3. Danika 4. Brent 5. Bill Tagging Information If you separate each item in your list with a blank line each item will automatically be tagged with a list item (:li.). Note: Ordered lists are similar to unordered lists but have a numbered item for each element in the list. ΓòÉΓòÉΓòÉ 8.15.5. Unordered Lists Information ΓòÉΓòÉΓòÉ This creates an unordered list. The following shows an unordered list as it is tagged: :ul. :li.One :li.Three :li.Two :eul. which will look like the following: o One o Three o Two Tagging Information If you separate each item in your list with a blank line each item will automatically be tagged with a list item (:li.). ΓòÉΓòÉΓòÉ 8.15.6. Simple Lists Information ΓòÉΓòÉΓòÉ This causes selected text to be tagged as a simple list. The following tags create a simple list: :sl. :li.Dog :li.Cat :li.Rabbit :esl. which generates: Dog Cat Rabbit Tagging Information If you separate each item in your list with a blank line each item will automatically be tagged with a list item (:li.). ΓòÉΓòÉΓòÉ 8.15.7. List Item Information ΓòÉΓòÉΓòÉ This is used to tag an item in a list. This tag works with any of the standard lists. The following list of names has each named tagged with :li.: :ul. :li.Mario :li.Mom :li.Dad :eul. which generates the following: o Mario o Mom o Dad The :li. were entered using list item command. The :ul. and :eul. were generated using the unordered list command. Note: You can press ALT-L to quickly insert the :li. symbol. Note: If you separate each list item with a blank line before marking the list the IPF Editor will automatically generate the list items for you. ΓòÉΓòÉΓòÉ 8.15.8. List Paragraph Information ΓòÉΓòÉΓòÉ This allows you to insert the list paragraph tag into a list of items. With this tag you can easily create a list of paragraphs that are automatically formatted. The following shows an unordered list with list paragraphs: :ul. :li.This is a list item. :lp.This is the first paragraph in the list and can be as many lines are you like. :lp.This is the second paragraph in the list associated with the first list item. :li.This is another list item (:li.). :eul. which generates the following list: o This is a list item. This is the first paragraph in the list and can be as many lines are you like. This is the second paragraph in the list associated with the first list item. o This is another list item (:li.). ΓòÉΓòÉΓòÉ 8.16. Lines Information ΓòÉΓòÉΓòÉ The Lines option lets you show text in the help manager exactly as you type it in the editor. The following text shows how to use this command: :lines align=center. The dog ran by. :elines. which generates the following: The dog ran by. ΓòÉΓòÉΓòÉ 8.17. Font Information ΓòÉΓòÉΓòÉ This menu option provides a method for changing the displayed font type and size in your document. To adjust the attributes of text, see the Highlighting options. The following shows setting a list of names in monospaced text: :font facename='System Monospaced' size=20x10. :ul. :li.Bill :li.Delaine :li.Danika :eul. :font facename='default'. which displays as the following: o Bill o Delaine o Danika The text is restored to the system default font after the marked text is set to the desired font. ΓòÉΓòÉΓòÉ 8.18. Margin Information ΓòÉΓòÉΓòÉ The Margin submenu allows you to set the left and right margins for you document. ΓòÉΓòÉΓòÉ 8.18.1. Left Margin Information ΓòÉΓòÉΓòÉ This allows you to specify the left margin for your document. The following shows normal paragraphs with the left margin set to 15 :lm margin=15. :p.This has a left margin of 15 :lm margin=1. which generates: This has a left margin of 15 The left margin is restored to 1 when we are finished with it so all further text will be normal. ΓòÉΓòÉΓòÉ 8.18.2. Right Margin Information ΓòÉΓòÉΓòÉ This allows you to specify the right margin for your document. The following sets the right margin to 20. :lm margin=1. :rm margin=20. :p.This has a right margin of 20 which will output: This has a right margin of 20 and a left margin of 1. ΓòÉΓòÉΓòÉ 8.19. HyperText/Graphics Link Information ΓòÉΓòÉΓòÉ The HyperText/Graphics Link menu option lets you create hypertext/graphics links from one part of your document to another. Hypertext/Graphics links can only be made to items tagged using the Header command or the footnotes command. Generally, you will not need to manually mark text and link it using this command if you use the auto-link option in the Application menu (it will automatically generate all links to headers and footnotes as they are encountered in your project). Tagging Information Mark the selected text then select the hypertext/graphics menu item or menu item. Note: Hyper-links can only be made to panel headings levels 1 through 4. ΓòÉΓòÉΓòÉ 8.20. Index Information ΓòÉΓòÉΓòÉ Use this to add primary or secondary level indices to your document. When you generate a primary index entry you will specify the "root words." "Root words" are the key words used by index synonyms, which are created automatically when you create an index entry. You must also supply the description entry to place into the index. This is a short text description which is what you will see in the index. Indices also require an ID, which is a brief text label used to link secondary and primary indices. The default ID is the first three characters of the descriptio entry. ΓòÉΓòÉΓòÉ 8.20.1. Index Creation ΓòÉΓòÉΓòÉ This page allows you to create indices in your document or index synonyms. This index entry will appear when the user selects the Help index from the help menu (or the from the options menu if in the VIEW.EXE program). ΓòÉΓòÉΓòÉ 8.20.1.1. Index Description ΓòÉΓòÉΓòÉ Place the index description in this field. If you leave this field blank a synonym tag only will be created, but no new index entry. ΓòÉΓòÉΓòÉ 8.20.1.2. Index Level 1 ΓòÉΓòÉΓòÉ Selecting this will generate a primary index. ΓòÉΓòÉΓòÉ 8.20.1.3. Index Level 2 ΓòÉΓòÉΓòÉ Selecting this will generate a secondary index. ΓòÉΓòÉΓòÉ 8.20.1.4. Index Root(s) ΓòÉΓòÉΓòÉ This field contains the roots for primary index entries or the root for a secondary index entry. Root words (roots) are index entries to specified topics. These root words are associated with words defined with the index-synonyms. Root words can contain alphabetic and numeric characters, and can be upper or lower case. When entering more than one root word place a space between each word. A root word in a synonym only creation is used to link to the primary index or secondary index entry. ΓòÉΓòÉΓòÉ 8.20.1.5. Index ID or Ref ID ΓòÉΓòÉΓòÉ This field contains the identifier for the primary index, or the reference indentifier for secondary index entries. ID and reference ID's are used to link primary and secondary index entries. ΓòÉΓòÉΓòÉ 8.20.1.6. Index Synonym Text ΓòÉΓòÉΓòÉ Enter the text for synonyms for this index. ΓòÉΓòÉΓòÉ 8.21. Symbols Information ΓòÉΓòÉΓòÉ This allows you to select from a list of commonly used symbols for use in your document. Some of the many symbols available are as show below: : - Colon ┬░ - Degree symbol ╤ü - Beta symbol ╨╝ - 1/4th symbol These symbols can be quickly placed into your text using the ALT-S command. ΓòÉΓòÉΓòÉ 8.21.1. Symbol List ΓòÉΓòÉΓòÉ This list provides you with the most common symbols supported by the IPF system. You may double click on an item or single click and then press "Select." ΓòÉΓòÉΓòÉ 8.21.2. Symbol List Select ΓòÉΓòÉΓòÉ Pressing this button, once you have selected a symbol from the symbol list, will cause the symbol to be placed directly into your IPF document. ΓòÉΓòÉΓòÉ 8.22. Group Panel Headings ΓòÉΓòÉΓòÉ This option will allow you to group selected headings together, displaying them on the same visible page. This means that whatever panels headings you have selected will share the displayed View or Help Manager window. Normally when a panel is displayed it replaces any previous panels shown. With this option you can easily and quickly provide multiple panels, each with related information. The IPF system refers to this as the Viewport. Of course you can still manually tag groups of headers together, but using the predefined types of header groupings saves a tremendous amount of time. ΓòÉΓòÉΓòÉ 8.22.1. Panel Heading Group Type ΓòÉΓòÉΓòÉ Select the type of panel header grouping you wish to include in your document for the marked headers. If you try to select a grouping that requires more panel headers than you have marked, you will receive an warning message and not be allowed to select it. The following panel header groupings are supported: o The selection will create a single panel that will be overlaid (not replaced) by the second panel selected. This will allow you to have two panels active that both fill the entire display area. o The selection will create a two panels that will share the display equally.The second window will not be shown until the user selects the hyperlink to it. o The selection will group three panels side by side, each using 1/3rd of the display. The second window will not be shown until the user selects the hyperlink to it. o The selection group four panels side by side, each using a quarter of the display. The second window will not be shown until the user selects the hyperlink to it. o The will place two headers in the display area, one on top of the other. The second window will not be shown until the user selects the hyperlink to it. o The will provide a parent panel along with multiple child windows, with each successive child window replacing the previous child window on the right side. The second window(s) will not be shown until the user selects the hyperlink to it. o The will generate two panels, side by side, that both appear immediately when the first is selected. o The will generate three panels, each using 1/3rd of the display, that will appear when the parent window is selected. o The will generate four panels, each using 1/4th of the display, that will appear when the parent window is selected. o The will generate two panels, with the parent on top and the child below it, with both of them appearing when the parent is displayed. ΓòÉΓòÉΓòÉ 8.22.2. Hide Child Panels ΓòÉΓòÉΓòÉ Selecting this will cause any child panels (any panel except the first panel marked is considered to be a child panel) to be hidden until its hyperlink is activated. ΓòÉΓòÉΓòÉ 8.22.3. Select Group Headers Type ΓòÉΓòÉΓòÉ Pushing this inserts the commands to generate the desired grouping into your document. ΓòÉΓòÉΓòÉ 9. Final Caveats ΓòÉΓòÉΓòÉ Special thanks for testing and debugging, and putting up with the work involved in this, to: o Mario Perez III ("Gee, does it work right now?", "It sure would be nice if it would...", and "This isn't right, is it?") o Mario Perez Jr. ("That works pretty well except for..." and "Where's the multi-tasking? Add a thread here...") o D.M.B. ("Are you done working on that program yet...") o D.A.B. ("I want to push the button!") o Brent Anderson ("Biking in mud's a lot more fun than programming...Let's go!") ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Perez Computing Services (PCS) is a software development company consisting of Mario Perez Jr. and Bill Perez. We have over forty years of programming experience between us and have written numerous applications for DOS, Windows, and OS/2. We provide custom programming as well as having several retail OS/2 and DOS software packages available. If you wish to contact us you may via U.S. mail or Compuserve, Prodigy, or IBMLINK's OS/2 BBS. Please make all contacts "attention Bill Perez." ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The Information Presentation Facility Guide is available from IBM either as part of the OS/2 2.x Technical Library or separately. You can contact IBM at 1-800-3-IBM-OS2 to order it. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ IBM and OS/2 are registered trademarks of International Business Machines Corporation. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Marked text is text you have selected by placing the cursor at it's beginning and highlighted by pressing the left mouse button and dragging the pointer over the text. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ This is a footnote.