Shareware Overload

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

/ Shareware Overload / ShartewareOverload.cdr / busi / ezhelp.zip / USERS.DOC < prev next >

Wrap

Text File | 1990-03-15 | 57KB | 1,578 lines

EZhelp Reference version 1.0 A Shareware reference tool (C) Copyright Brain Child Systems, 1990 All rights reserved Table of contents - EZhelp Reference I. Introduction to EZhelp 1 A. What's EZhelp? 1 B. EZhelp features 2 C. Three easy steps 2 D. Defining reference use 3 II. Writing text 3 A. Forming an outline 3 1. Example outlines 4 B. Creating topics 6 1. Topic Descriptions 6 2. Menu Groups 6 3. Example reference 7 C. Entering reference text 9 1. Reference file layout 9 2. Guidelines 10 III. Compiling text 11 A. Command line 11 B. Reporting 12 IV. Using EZhelp 13 A. Memory needed 13 B. Starting from within your application 13 C. Command line 13 1. Examples 14 2. Using Showcolo.exe 15 3. Error messages 15 D. Distribution 16 E. Source code 16 F. Registering 17 G. Enhancements 17 H. Quick summary 18 Appendix A Installing EZhelp Reference Appendix B EZhelp developer's overview Appendix C EZhelp developer's function reference Page 1 I. Introduction to EZhelp A. What's EZhelp? EZhelp is a shareware product designed as a tool for writers or programmers who need a simple help system to use stand-alone, link with existing software, or use as an on-line reference. You can easily create a window driven help system with new or existing texts, and registered users may distribute EZhelp with them free of charge. In addition to the executable version of EZhelp, source code is available to developers who wish to incorporate EZhelp into their applications. For more information, see the section on Registering on page 17. This user's documentation is also organized into an EZhelp text file, and you can see how the program works by typing "EZ" at the DOS prompt to begin. Since this is version 1.0 of the program, any feedback you have would be valued. There are many possible features that could be added, and this will depend on what you ask for. If you try the program and have an opinion, drop us a line! EZhelp consists of three programs: EZcomp.EXE - A text compiler program that creates an index on help reference files you have created. This index file describes where topics begin and end within the text. EZhelp.EXE - The program that uses the help file and the index created with the compiler to drive the windows and text display. Showcolo.EXE - A utility to display colors and their values, to assist in choosing colors for menus and windows. You will need a text editor or word processor to create your text files with. There are a few issues to be aware of when using a word processor. For more information, check the section on Entering Text on page 9. You will be more successful with this package if you follow the hints on organizing your topics. More information can be found in the Forming Outline section on page 3. _________________________________________________________ EZhelp Reference (C) Copyright 1990, Brain Child Systems. All rights reserved. Page 2 B. EZhelp features * Pop-up menus - EZhelp menus automatically position on the screen, and anchor to previous menus. All backgroung screen areas are saved and restored when the menu or window is removed. * Fast display - EZhelp uses optimized functions to keep the screen display and update as fast as possible. * Sizeable text window - You can specify the size of the help text window, ranging from 4 lines to 23 lines. * Choice of colors - You can specify the colors of the menus, highlight bar, and text on the command line when you start EZhelp. * Choice of line style - You can specify the border line style that EZhelp is to use. * Start at any menu level - You can start EZhelp at any menu level or menu group using a command line option. * Jump directly to any help topic - You can jump directly to the help text of any topic in any menu - avoiding the display of the menu. * Optional sorting of topics - You can easily organize your menu topics by a predetermined order, or have them sorted and displayed alphabetically. * Flexible use - Topic sections within your help text do not need to be in the same order as menu items are to appear. The EZcomp text compiler locates all menu items in your text automatically. * Reference report - A reference report is available as a command-line option with EZcomp, the text compiler. This report lists all menus, topics, and links between menus. Line numbers are also shown in the report, to aid you in locating topics in your help text file. * Free program updates - All registered users will be notified of updates, and can obtain free updates for one year, less shipping and media costs. C. Three easy steps There are three steps to creating your own menu-driven help reference text. First, working from a broad outline, organized like a table of contents or hierarchical chart, write out Topic Descriptions associated with each item of help text, and insert them into the reference file using a text editor or word processor. Next, compile the reference file using EZcomp, which creates an index file to be used with the text. Page 3 After the index has been created on the reference file, you can test the menus and display of each topic using EZhelp. You can try the various options available when EZhelp is started, until you have the menus and windows like you want them. If you already have specific text written (on disk), you should be able to easily insert Topic Descriptions based on an existing table of contents. This will serve as a complete reference of the entire application or manual. The following section should be read beforehand, to pinpoint the type of functions that EZhelp should perform. D. Defining reference use Before sitting down to write out the Topic Descriptions for use in the reference file, you should give some thought to the type of use the reference will be needed for. A few specific questions you can ask are: 1) Is the reference to be organized around existing user's documentation, or should it conform more closely to the application itself? 2) Is the reference to be used for field-level help, where menus do not display, and the help text displays directly? 3) Do you prefer a single-level menu or multiple-level menus leading to the topic? 4) How large is the window to be used with the text? These questions will have an impact on the relation between the menu topics you create and the behavior of the menus when the program is running. You can create menus to accomodate all of the above needs, all within the same reference file. II. Writing text A. Forming an outline Writing an outline is the essential first step to creating the reference. It helps to begin with the most general subjects, and narrow the subjects into sub-topics and further sub-topics. The outline itself should have no more than sixteen levels of sub-topics. The outline will show the relationships of menus in your reference. You should define your menus in terms of the type of reference you want to create, whether it is to contain a complete topic index with multiple menu layers, or just field-level help. Page 4 Following is a simple example of an outline for a reference file example, with three levels of topics: Outline example 1: As organized in an EZhelp Methods of transportation Reference file I. Land Land, Water, and Air will be assigned menu number 1. a. Car b. Bicycle Car, Bicycle, and feet will c. Feet be assigned menu number 2. II. Water a. Speedboat Speedboat, Yacht, and Jet ski b. Yacht will be assigned menu c. Jet Ski number 3. III. Air a. Airplanes Airplanes and Hot air ballon will be assigned menu 1. Prop plane number 4. 2. Glider 3. Jet Prop plane, Glider, and Jet will be assigned menu b. Hot air baloon number 5. This outline example would be useful to create a reference modeled after users documentation, or where the topic is too complex to cover with one choice. Page 5 Following is another example with the same topics, reorganized into single-level menus. Outline example 2: As organized in an EZhelp Methods of transportation Reference file a. Land The assignment of menu numbers b. Water would be the same in this c. Air example. The difference here is that all menus are single a. Car level, and the associated b. Bicycle reference would display after c. Feet the topic is chosen. a. Speedboat This outline would be most b. Yacht useful when a general c. Jet Ski reference of a page or less should be given on a topic. a. Airplanes b. Hot air baloon This type of outline can also be used to accomodate a. Prop plane field-level help topics b. Glider where the menu is not c. Jet displayed. The next section, Creating Topics, shows how to create Topic Descriptions from a general outline, and how you can create menu groups of Topic Descriptions to use as complete references, single-level menus, and field-level displays. Page 6 B. Creating Topics Topic Descriptions The Topic Descriptions to be displayed in the pop-up menus can be created from the outline. The topic itself is a line of text that is inserted in your document, just above the point where the help text begins for that topic. The topic consists of a topic name and three additional parameters: {{ Topic Name, Menu No., Menu Order, Next Menu }} * {{ - double brackets placed in the text will begin a topic definition. A topic definition is ended with another set of brackets }}. * Topic Name - you may use up to fifteen characters for the topic, beginning with the first non-blank character after the brackets. * Menu No. - this will identify the group of topics which are to be shown on the same menu. The outermost menu, or most general, should begin with 1 as a rule. * Menu Order - this will specify the order of the topic among the other topics in the menu, from top to bottom. If you wish the menu topics to be sorted alphabetically, use 0 for the order number in each topic in the menu. * Next Menu - if this topic leads to another topic sub-menu, use the sub-menu number. If this topic leads to the help text (the help text follows the topic in the document), use 0. Following this paragraph is a sample set of topic definitions for a reference describing methods of transportation. Note that the reference text for topics would be inserted after the topics where the Next Menu parameter is equal to zero, but for clarity, the text is omitted here. Menu Groups Menu groups allow you to duplicate topic names, or offer the same topic in different ways. The examples in the section on Forming an outline will be used here to create the Topic Descriptions for a reference on Methods of Transportation. Page 7 Example reference file: Transpor.txt Subject: Methods of transportation EZhelp Topic Descriptions for reference Transpor.txt {{ Land, 1, 1, 2 }} {{ Water, 1, 2, 3 }} menu 1, 3 topics {{ Air, 1, 3, 4 }} ____________________ {{ Car, 2, 1, 0 }} {{ Bicycle, 2, 2, 0 }} menu 2, 3 topics {{ Feet, 2, 3, 0 }} ____________________ {{ Speedboat, 3, 1, 0 }} {{ Yacht, 3, 2, 0 }} menu 3, 3 topics {{ Jet ski, 3, 3, 0 }} ____________________ {{ Airplanes, 4, 1, 5 }} menu 4, 2 topics {{ Hot air baloon, 4, 2, 0 }} ____________________ {{ Prop plane, 5, 1, 0 }} {{ Glider, 5, 2, 0 }} menu 5, 3 topics {{ Jet plane, 5, 3, 0 }} ____________________ In menu number 1, topic "Land" defines the following menu, number 2. Also in menu 1, topic "Water" defines next menu 3, and topic "Air" defines next menu 4. Topic "Airlines" defines a third menu level, 5. This group of Topic Descriptions above fits the hierarchical type of outline, which most closely matches user's documentation. But suppose that this structure is not sufficient at all times. At certain places in your application, you want the topic "Land" to lead directly to a reference text window, instead of a sub-menu with Land topics. All you would need to do is add another menu, perhaps identical to menu 1 defined above, but give it another menu number: {{ Land, 10, 1, 0 }} {{ Water, 10, 2, 0 }} menu 10, 3 topics {{ Air, 10, 3, 0 }} ____________________ You could place these definitions anyplace in the reference file, and follow the topic "Land" with the associated help text. The example above would allow "Water" and "Land" to lead directly to help text rather than another menu, because the Next Menu parameter is zero. Page 8 Later, when you want to access the topic "Land" in menu 1 or menu 10, you can start EZhelp and specify the startup menu number. If topic "Land" in menu 10 corresponds to a field level help item, that is, you don't want a menu to show, but to go directly to the display of the reference text, you can call EZhelp specifying the startup menu number and the topic to jump directly into. * Starting at the default menu, number 1 EZhelp Transpor.txt This will start EZhelp with Transpor.txt, which contains the above Topic Descriptions, and begin at the default menu number, 1. In this example, the menus and reference text of menu 10 will not be accessible. * Starting at a specific menu number EZhelp Transpor.txt -M10 This will start EZhelp at menu 10, showing all three topics of the menu. All other menus would not be accessible. * Jumping directly to a topic EZhelp Transpor.txt -M10 -J1 -S4 This will start EZhelp at menu 10, but instead of showing the other topic of menu 10, the reference text below topic "Land" would display directly, in a text window of 4 lines. NOTE: If you choose to enter zero for each Menu Order parameter in the Topic Description line, you cannot use the -J option to jump directly to a topic. _________________________________________________________ If you like, you can start the above examples using the DOS batch files EX1.BAT, EX2.BAT, and EX3.BAT supplied with the diskette. The full set of EZhelp command-line options are described in more detail on page 13. As the above examples show, you can create isolated menus within the reference text for different purposes. The next section, Entering text, shows the general layout of the reference file, including Topic Descriptions. Page 9 C. Entering text Reference file layout ---------------------------------- This is the basic layout of an EZhelp Reference file: +---------------------+ |.beginning of file | | | |Comments (a) | (a) Optional comments may be placed | | at the beginning of the file, until |Topic definition (b) | the first Topic definition. | | |Accompanying text (c)| (b) A topic definition line should | | always be followed with Accompanying |Topic definition (b) | text unless another menu is to | | follow. |Accompanying text (c)| | | (c) The accompanying text will be |Topic definition (b) | assumed to continue until the next | | topic definition is found, or the |Accompanying text (c)| end of the file is reached. | | |.end of file | +---------------------+ It helps to use the first part of the reference file for comments, before the first topic definition. Take a moment to examine Transpor.txt with your text editor. At the top, you'll see a table where information on the topics and menus is kept. This is useful as an overview of the reference text once you have begun to write. Additional comments You can create additional comment sections in your reference file by defining a Topic Description with a menu number that is never used. For example, you could designate 199 to be a menu number that indicates a comment section: {{ dummy menu, 199, 0, 0 }} All comments after this Topic Description and before another Topic Description would not be displayed (assuming that you never start EZhelp with menu 199 as the startup menu). Page 10 Guidelines for Topic Descriptions and reference text files An EZhelp Reference file MUST conform to these guidelines: 1) Carriage return/line feed (CR/LF): A carriage return/line feed pair must terminate every line in the file. What this means for text written with many commercial word processors (Microsoft Word, Wordperfect, others) is that it will likely be neccessary to press the return key at the end of each line, rather than letting the line wrap around. One way to tell if your word processor generates the CR/LF at the end of each line is to use the DOS "TYPE" command to view the text file on the screen. If the text is not indented as you would see it in the word processor, then you will need to press return at the end of each line. Avoid using the tab key in the text. Instead, indent using the space bar. All text formatting commands used by your word processor (bold, underline, etc.) should be avoided also, if your word processor cannot save a file unformatted. The finished reference that you want to use as an EZhelp file must be saved unformatted. 2) Completeness of Topic Descriptions Each Topic Description must have a complete set of elements. This includes an opening set of brackets, a Topic Name and comma, Menu Number and comma, Menu Order and comma, Next Menu, and a closing set of brackets. An incomplete Topic Description could cause the compiler to hang up. 3) Line length: A line must be 74 characters or less. If the line is longer than 74 characters, unexpected results may occur. One common result is when the entire page shifts up by one line. Take care to follow this guideline. 4) Recompiling: The reference file must be recompiled after each time it is modified. If it is not recompiled, the help text displays will overlap, and the topic definition line may be visible on the screen. Page 11 5) File size The reference file may be as large as the unused memory on your system, up to 640k. This should not be a limitation, but if you need to know how much memory you have available, run the DOS Chkdsk command. 6) Number of menus and topics You may create up to 255 menus, with a maximum of 100 topics in each menu. The maximum number of menu levels is 16. III. Compiling text An index file is created for each reference file before it used with EZhelp. The index file keeps information on the topics and menus, and uses it to find the topic's text in the reference file. The index file name is automatically created using the first part of the reference file name and adding ".hnx" as the extension. The index file will be placed in the same subdirectory as the text file. "myfile.txt", when compiled, creates an index "myfile.hnx". +--------+ +---------------+ +---------+ | | | | | | | Text |-----> | EZcomp.exe |-----> | Text | | file |-----> | (compiler) |-----> | index | | | | | | | +--------+ +---------------+ +---------+ A. Command line EZcomp MYFILE.TXT [-pu] [-ps] From the DOS prompt, enter the following command to compile a help text file: EZcomp MYFILE.TXT The compiler runs for a moment, creates the index "myfile.hnx" using the text file "myfile.txt", and returns to the DOS prompt. To compile the text and print an unsorted report of the topics, enter this command: EZcomp MYFILE.TXT -pu To print a sorted report of the topics, substitute "-ps" on the command line, or include both "-pu" and "-ps" for both reports. Page 12 B. Reporting Topic report Shown below is a portion of the topic report generated by EZcomp.exe. The reference file used was EZhelp.txt. The report can be printed sorted or unsorted using the command line options. If you give each topic a number in the Menu Order parameter of the Topic Description line, the report will be identical whether sorted or unsorted. ---------------------------------------------------------------------- EZcomp v1.0 Reference Index report, unsorted: ezhelp.txt Page 1 ---------------------------------------------------------------------- Menu Menu Next Line Line number order Topic menu number count Offset Size ------ ----- --------------- ----- ------ ------ ------ ------ 1 1 What's EZhelp? 8 91 244 2779 1 2 3 easy steps 99 22 3051 462 1 3 Writing text 2 121 4 3541 35 1 4 Compiling text 3 125 4 3604 35 1 5 Using EZhelp 4 129 4 3667 35 1 6 Registering 133 70 3730 2923 1 7 --------------- 203 2 6681 4 1 8 CharityWare? 205 47 6713 2135 Items in the report Menu number, Menu order, Next menu, Topic - These are the same as the parameters entered in the Topic Description. Note that if zero is entered as the Next Menu parameter, blanks will show on the report. Line number - This is the line in the reference file where the topic is found. Line count - This is the total number of lines of the reference text of the topic, including the Topic Description line. Offset - This is the offset in bytes, from the beginning of the file, where the Topic Description begins. Size - This is the total number of bytes of the reference text of the topic, including the Topic Description line. Page 13 IV. Using EZhelp Memory needed EZhelp menus and help text windows allocate and release memory as they are used. The amount of memory required will depend on the size and levels of the menus. The .EXE version of the program will use up to 64k. If there is no free memory to allocate, the program will exit. If the error message flag (see Command line below) is set on, an error message will display. The EZhelp .OBJ libraries use less than 7k when linked into your applications. Starting EZhelp from within your application You can start EZhelp from within your applications and arrange the menus and help to complement your program's operation. If you are a C user, you can link in the EZhelp libraries, and if you are using dBASE, you can use the Run command to use the .EXE version. If your language of choice has a facility to start another DOS program while your program is running, then you can use EZhelp. All screens are restored to their original state before EZhelp exits, and EZhelp will return error codes to your program to indicate if it terminated abnormally. This design keeps your program in control. dBASE users may not be able to detect returned error codes, however. Command line EZhelp MYFILE.TXT [-Mnn -Jnn -Wnn -Bnn -Snn -Tnn -E ] where... MYFILE.TXT The name of a text reference file to be used. Up to 40 characters may be used for the full path and file name. The index MYFILE.HNX is assumed to reside in the same subdirectory. -Mnn The number of the menu to start at. The program will begin by displaying the Topic Descriptions for that menu, as defined in MYFILE.TXT. All subsequent menus from the point of the startup menu will be accessible. The default startup menu is number 1. -Jnn The number of the topic in the startup menu to display directly. If the -Jnn option is used, the menu will not be shown, and the help text for topic -Jnn in menu -Mnn will display. Page 14 -Wnn A number to define the color of the menu window borders, non-highlighted menu items, and the help text display. If a number is not specified, the default is 7, white. -Bnn A number to define the color of the menu highlight bar. The the default is 30, yellow on blue. -Snn A number to define the size (in lines) of the help text window display. The minimum window size is 4, and the maximum is 23. The default is 23 lines. -Tnn A number to define the menu and help text window borders. The different styles available and their numbers are show below. The default is 1. ┌───┐ ╒═══╕ ╔═══╗ ╓───╖ │ 1 │ │ 2 │ ║ 3 ║ ║ 4 ║ └───┘ ╘═══╛ ╚═══╝ ╙───╜ single line single on double line double on sides, double sides, on top single on top ▓▓▓▓▓ ▒▒▒▒▒ ░░░░░ ▄▄▄▄▄ ▓ 5 ▓ ▒ 6 ▒ ░ 7 ░ ▌ 8 ▐ ▓▓▓▓▓ ▒▒▒▒▒ ░░░░░ ▀▀▀▀▀ . . . . . . . special characters . . . . . . . -E This option will turn error messages on. The default is no error messages. When you are initially developing the reference, you should run with this option on, to trap any errors. If an error condition occurs, the message will display until you press a key. Examples 1) EZhelp MYFILE.TXT Start MYFILE.TXT at menu 1, use all defaults. 2) EZhelp MYFILE.TXT -M4 -J7 -S15 Jump directly to the display of topic 7 in menu 4. Use a text display window of 15 lines. Page 15 3) EZhelp MYFILE.TXT -W1 -E Start MYFILE.TXT at menu 1, using a window color of blue. Turn error messages on. Note: The order of the options specified is not critical. Using Showcolo.exe A utility program, Showcolo.exe, is included with this program to allows you to view color values that can be used by the program. To start at the DOS prompt, type SHOWCOLO. The menu box will display at the bottom of the screen. Use the arrow keys to change the foreground or background of the border or bar where the marker is positioned. To move the marker, press Tab or Return. The values displayed for each color correspond to the color that will be shown when EZhelp is started with that value. Error messages There are four error conditions that can be encountered. The following list describes each: * EZhelp... help file not found. The help reference file was not located in the path specified in the filename parameter. If no path is specified, the file is assumed to reside in the same directory as EZhelp.exe. * EZhelp... index file not found. The index file was not located in the same directory as the help reference file. * EZhelp... insufficient memory. EZhelp could not allocate the memory required for the index, menu or help window. * EZhelp... topic not found. EZhelp could not find the chosen topic in the reference file. If EZhelp was started with the -J parameter, perhaps the number was incorrect. If this error occurs without the -J parameter, the Next Menu specified in the Topic Description chosen may be incorrect, or the Next Menu may not exist in the reference file. Page 16 D. Distribution Unregistered and registered users may distribute copies of this Shareware package for the trial use of others, and we encourage you to do so. Source code purchased by registered users may not be distributed for the trial use of others. A reasonable "disk fee" or postage fee may be charged for the distribution of this package, but that fee is not to exceed US $7.50 under any circumstances without the written consent of Brain Child Systems. Registered users may bundle EZhelp.exe with their own applications and distribute unlimited copies. If a registered user distributes EZhelp.exe, the file name may not be changed. Registered users may also link EZhelp object files into their applications without further obligation. E. Source code EZhelp source code is available for Turbo C compilers, and the source code for EZcomp is also included. This includes source for the small memory model and instructions on the few simple changes necessary to convert to other memory models. Support for Microsoft C is being added and will be available in the next version. For current pricing information, see the order form (ORDER.DOC). Source updates will be available at half their original cost, for two years, plus media and postage costs. When an update becomes available, registered users will be notified. If you have a special need that is not met by EZhelp, or an idea for an enhancement, send a note with details. There is a chance that the feature may have been included in an updated version. If not, we will do our best to make good use of your valuable suggestions. For a list of the currently planned enhancements for version 1.1, see page 17. Page 17 F. Registering EZhelp is a shareware product, and may be used for a reasonable trial period free of charge. What defines a reasonable trial period? You may evaluate the package for 30 days, which should be enough time to decide if you would like to continue using it. The basic registration fee is $25. This fee includes a diskette with all EZhelp executable files, Turbo C object file libraries for all memory models, a user's guide on the diskette, and free updates for one year, less media and postage costs. After one year, registered users can obtain updates for half of the original fee. Documentation on each function is also included with basic registration, for application developers. Source code updates can be obtained for half of the original price. To print out a copy of the registration form, use this DOS command: TYPE ORDER.DOC > PRN Disclaimer This program is sold without any express or implied warranties whatsoever. Because of the diversity of conditions and hardware under which this program may be used, no warranty of fitness for a particular purpose is offered. The user is advised to test the program thoroughly before relying on it. The user must assume the entire risk of using the program. Any liability of seller or author will be limited exclusively to product replacement or refund of the purchase price. G. Enhancements Here is a list of enhancements that are being considered for version 1.1 of EZhelp. The ones with an asterisk are most likely to be included in the next version. * Additional help window messages * Single-line scrolling * Single-letter menu selection * Hands-free Demo mode Menu names at the top left of each menu Front end with text editor More startup options Help text printing Page 18 H. Quick summary Topic definitions {{ Topic Name, Menu No., Menu Order, Next Menu }} 1 - 15 chars all of the 0 for sort on 0 for display ended with a topics in topic name; text to follow; comma a menu have Other - use Other - display the same # order chosen the next menu Compiling text EZcomp MYFILE.TXT [-pu] [-ps] Note: Use your own help text file in place of MYFILE.TXT. Use the -pu and -ps options to print a report on the text file topics, unsorted or sorted. Running EZhelp EZhelp MYFILE.TXT [-Mnn -Jnn -Wnn -Bnn -Snn -Tnn -E ] -Mnn menu number -Jnn jump to topic in menu -Wnn window color -Bnn bar color -Snn window size -Tnn window style -E turn on error messages Appendix A Installing EZhelp Reference To install EZhelp Reference onto another drive, enter the following commands at the DOS prompt. First, set the DOS prompt to the drive where the EZhelp files reside. A: (get the source drive prompt) Then, start the installation batch, giving the source drive and the drive where the files are to be installed. INSTALL X Y (where X is the letter of the source drive and Y is the letter of the destination drive. For example, if you want to install EZhelp on your C drive, enter INSTALL A C This installation batch will create two subdirectories on the destination drive, \EZHELP and \EZHELP\TCLIB. \EZHELP subdirectory contents EZhelp.exe command line executable module EZcomp.exe reference compiler Showcolo.exe color display utility EZhelp.txt EZhelp user's reference EZhelp.hnx EZhelp user's index Transpor.txt Example reference Transpor.hnx Example index Anchor.txt Example reference Anchor.hnx Example index Users.doc User's documentation Order.doc Order form Install.bat Installation batch EZ.bat Batch to start user's reference Ex1.bat Batch to start example 1 Ex2.bat Batch to start example 2 \EZHELP\TCLIB subdirectory contents EZT.LIB tiny model EZS.LIB small model EZC.LIB compact model EZM.LIB medium model EZL.LIB large model EZH.LIB huge model \EZHELP\SRC subdirectory contents EZhelp.h EZhelp header file Yourprog.c Sample application with EZhelp link If you purchased source code, the source files below will also be installed in the \EZHELP\SRC subdirectory: EZhelp.c command line executable source EZ_help.c application linkable source EZhelp1.c EZhelp function source EZhelp2.c Toolbox function source EZcomp.c Reference compiler source Appendix B EZhelp developer's Overview This appendix deals with the library files and setting up to link to your application. There are six library files contained in the \TCLIB subdirectory on the EZhelp diskette. These library files contain the .OBJ files in each memory model, for Turbo C. EZT.LIB tiny model EZS.LIB small model EZC.LIB compact model EZM.LIB medium model EZL.LIB large model EZH.LIB huge model The .OBJ files contained in each .LIB file have the same names, so if you intend to extract the .OBJs files for linking, take care not to mix the files from each library. EZHELP.OBJ command line startup EZ_HELP.OBJ function call startup EZHELP1.OBJ EZhelp functions EZHELP2.OBJ Toolbox functions There are two ways you can link the required functions into your application. If you use the integrated environment and project files, include EZ_HELP.OBJ, EZHELP1.OBJ, and EZHELP2.OBJ in your project file. If you use TLINK, Borland's command line linker, name the library to use as in the following example, which assumes that the EZhelp diskette is in the A drive. This example links in the small memory model, using an application's object file, YOURPROG.OBJ, and the Turbo C object file c0s.obj. The EZhelp library file EZS is included, along with the Turbo C libraries cs.lib, maths.lib, and emu.lib. tlink \tc\lib\c0s YOURPROG.OBJ,YOURPROG.EXE,,A:\TCLIB\EZS \tc\lib\cs \tc\lib\maths \tc\lib\emu Note: The entire command was broken into two lines for clarity. To link for other memory models, you must specify the correct Turbo C memory model objects and libraries. Tiny model tlink \tc\lib\c0t YOURPROG.OBJ,YOURPROG.EXE,,A:\TCLIB\EZT \tc\lib\cs \tc\lib\maths \tc\lib\emu Small model shown in example above Compact model tlink \tc\lib\c0c YOURPROG.OBJ,YOURPROG.EXE,,A:\TCLIB\EZC \tc\lib\cc \tc\lib\mathc \tc\lib\emu Medium model tlink \tc\lib\c0m YOURPROG.OBJ,YOURPROG.EXE,,A:\TCLIB\EZM \tc\lib\cm \tc\lib\mathm \tc\lib\emu Large model tlink \tc\lib\c0l YOURPROG.OBJ,YOURPROG.EXE,,A:\TCLIB\EZL \tc\lib\cl \tc\lib\mathl \tc\lib\emu Huge model tlink \tc\lib\c0h YOURPROG.OBJ,YOURPROG.EXE,,A:\TCLIB\EZH \tc\lib\ch \tc\lib\mathh \tc\lib\emu The libraries are configured to allocate memory for that specific memory model. The allocation calls used in each model are: EZT.LIB malloc() EZS.LIB malloc() EZC.LIB malloc() EZM.LIB farmalloc() EZL.LIB farmalloc() EZH.LIB farmalloc() If you purchased source code, you will have to change the malloc() calls with farmalloc() calls, and the free() calls to farfree() calls, to compile in the Medium, Large, and Huge memory models. There are 11 places in the code where the calls are found, as listed below: Source file malloc() free() ----------- ----------------------- --------------------- EZ_HELP.C line 49, 50, 71 line 118, 119, 120 EZHELP.C line 133, 134, 157 line 188, 189, 190 EZHELP1.C line 121, 131, 551, 553 line 223, 224, 253, 256, 643, 644 EZHELP2.C line 188 line 225 Appendix C EZhelp developer's function reference This appendix lists the major functions of the EZhelp system. Only one function from these listed here is needed to call EZhelp from another application. This function is ez_help. Because of its emphasis, it is listed first. The remainder of the functions are grouped into two sections, EZhelp and Toolbox. The several that may be useful in any application are listed in the Toolbox section. The rest of the functions are useful only within the EZhelp system, and are grouped together at the end. Toolbox functions ez_help File: EZ_help.obj -------------------------------------- int ez_help(ezhelp_env *env) This is the function to link into your application to call EZhelp. The function requires that you declare a ezhelp_env structure and fill it with any startup options needed. This fields of this structure are defined in EZhelp.h. ezhelp_env pointer to an ezhelp_env structure declared in your calling program. env->start_menu should be set with the character value of the startup menu. For example, if you were to start EZhelp at menu number 10, you would include this line in your program before calling ez_help: env.start_menu = (char)10; Additional options may be set in ezhelp_env structure env before calling ez_help. For further examples, see the sample program Yourprog.c and header file EZhelp.h. Returns: An integer indicating an exit (error) code is returned to the calling program. The possible exit codes are: 50 insufficient memory 51 topic not found 53 reference file not found 54 reference index not found calculate_framemem File: EZhelp2.obj -------------------------------------- Calculate the amount of memory needed for a menu buffer, including the outer window and color character, with one extra space on each side of each side of topics, and one extra line above the first topic. void calculate_framemem(int *framemem, menu_env *mnptr, ezhelp_env *env, int scrn) framemem pointer to the integer which will be set in this function with the calculated memory requirement mnptr pointer to current menu status buffer env pointer to environment buffer scrn current menu level getkey File: EZhelp2.obj -------------------------------------- Get a key from the keyboard buffer and return the scan codes in two characters passed to the function void getkey(char *key, char *asct) key pointer to char asct pointer to char Returns: Contents of AH register returned in key, contents of AL register returned in asct. hidecursor File: EZhelp2.obj -------------------------------------- void hidecursor() Remove the cursor from the screen. monochrome File: EZhelp2.obj -------------------------------------- int monochrome() Test for a monochrome monitor. Returns: TRUE if a monochrome monitor is found FALSE if any other monitor is found putframe File: EZhelp2.obj -------------------------------------- Putframe will allocate the memory to build a screen buffer, fill it with the window in the style and color specified, then place it on the screen. The memory is released before return. void putframe(char botype, char bocolo, int balong, int bahigh, int xcoord, int ycoord) botype which window style (1 - 8) bocolo color of window frame balong number of chars from left to right bahigh number of lines from top to bottom xcoord upper left x coordinate ycoord upper y coordinate showcursor File: EZhelp2.obj -------------------------------------- void showcursor() Return the cursor to the screen. sizecursor File: EZhelp2.obj -------------------------------------- This function will set the cursor size to 0 lines, or reset it back to 1 line, as is the default. void sizecursor(int on) on if 0, set cursor lines to 0, else set cursor line to 1. EZhelp functions count_topics File: EZhelp1.obj -------------------------------------- Count the total number of topics in a menu, put the results in mnptr->lblset. Put the number of the first menu in the set, from the beginning of the index, in mnptr->frst_lbl. int count_topics(indextype *txptr, menu_env *mnptr, ezhelp_env *env) txptr pointer to help text index mnptr pointer to current menu status buffer env pointer to environment buffer drive_bars File: EZhelp1.obj -------------------------------------- This function controls the menu display and selection. The major functions performed are: * memory requirements calculated, memory allocated * topics loaded from index into screen buffer * memory allocated for underlying screen area, and filled * menu window placed on screen * topics placed within window boundaries * highlight bar control int drive_bars(int *last_keypress, indextype *txptr, menu_env *mnptr, ezhelp_env *env) last_keypress 1 if return was the last keypress before this function was called. This variable is also set by this function. txptr pointer to help text index mnptr pointer to current menu status buffer env pointer to environment buffer Returns: 0 if escape is pressed 1 if return pressed and another menu level exists 2 if return pressed an no more menu levels exist other by error code Returns: error codes drive_help File: EZhelp1.obj -------------------------------------- This function performs the outer control of the menus and help display: * calls the other functions that seek and load topics for display and selection. * increments and decrements the menu-level pointer * call show_helptext when it is appropriate to display help text. int drive_help(FILE *F_help, menu_env *mnptr, indextype *txptr, ezhelp_env *env) F_help reference file pointer mnptr pointer to current menu status buffer txptr pointer to help text index env pointer to environment buffer give_exit_msg File: EZhelp1.obj -------------------------------------- Display an error message to the screen, if env->show_errors is TRUE void give_exit_msg(int whicherror, ezhelp_env *env) whicherror integer of the message to display (see function ez_help for a list of possible error codes) env pointer to environment buffer insert_nulls File: EZhelp1.obj -------------------------------------- Read through the help text in the buffer, inserting a NULL on the line feed character after n line feed characters have been counted, where n is the window size, in lines. void insert_nulls(char *text, int *num_pages, indextype *txptr, ezhelp_env *env) text char pointer to the buffer containing the help text num_pages pointer to integer. This variable will bet set in this function with the number of pages of the help text. txptr pointer to help text index env pointer to environment buffer load_help File: EZhelp1.obj -------------------------------------- Loads the help text topic from the reference file at the offset contained in txptr int load_help(FILE *help_file, char *text, int *num_pages, indextype *txptr, ezhelp_env *env) text pointer to the help text (filled in this function) help_file pointer to the help text file num_pages pointer to integer, to be set with the number of pages of text txptr pointer to help text index env pointer to environment buffer Returns: Zero is returned on success. load_topics File: EZhelp1.obj -------------------------------------- Read all of the topics of a given menu into a buffer, back to back void load_topics(int *dash, indextype *txptr, char *lbltxt, menu_env *mnptr, ezhelp_env *env) dash pointer to a flag indicating if line is all dashes txptr pointer to help text index mnptr pointer to current menu status buffer lbltxt pointer to buffer area to receive topics env pointer to environment buffer next_page File: EZhelp1.obj -------------------------------------- Rewind or fast forward to the next page of text. void next_page(int which_way, char *text, int *done) which_way if 0, rewind; else fast forward text pointer to the help text done pointer to integer of the total number of character rewound or fast forwarded. This variable is set in this function. seek_topic File: EZhelp1.obj -------------------------------------- Read through the help text index to match the topic contained in mnptr. The first two characters of mnptr->menulink must be filled with Menu Number, Menu Order values. If env->jump_to is non-zero, the second character of mnptr->menulink will be set to that value. Mnptr->topic must also be filled with the topic name. int seek_topic(menu_env *mnptr, int *mnunum, indextype *txptr, ezhelp_env *env) mnptr pointer to current menu status buffer mnunum number of the topic in the index, from the start of the index txptr pointer to help text index env pointer to environment buffer Returns: TRUE if topic found in index Returns FALSE otherwise show_helptext File: EZhelp1.obj -------------------------------------- This function controls the display of the help reference text. The major functions performed are: * memory allocated for the entire topic * memory allocated for underlying screen area, and filled * topic read into buffer from file, page nulls inserted * all underlying screens are restored for each menu level * help window displayed, help reference displayed * PGUP and PGDN through text int show_helptext(FILE *F_help, indextype *txptr, menu_env *mnptr, ezhelp_env *env) F_help reference file pointer txptr pointer to help text index env pointer to environment buffer Returns: error codes show_next_menu File: EZhelp1.obj -------------------------------------- This fnction will attempt to locate a menu number in the index based on the char value contained in mnptr->menulink[0]. If the menu is found, the function drive_bars is called to display it. int show_next_menu(int *last_keypress, indextype *txptr, ezhelp_env *env, menu_env *mnptr) last_keypress 1 if return was the last keypress before this function was called. This variable is also set by this function. txptr pointer to help text index env pointer to environment buffer mnptr pointer to current menu status buffer Returns: error code if menu not found show_windowmsg File: EZhelp1.obj -------------------------------------- Place the page number and keystroke command message at the top of the help text window. The variables curset and num_pages are used to determine if the message should contain PGUP, PGDN, both, or neither. void show_windowmsg(int curset, int num_pages, ezhelp_env *env) curset current page of text num_pages total number of pages in text env pointer to environment buffer unroll_menus File: EZhelp1.obj -------------------------------------- void unroll_menus(int scrn, menu_env *mnptr) Restore each menu level underlay to the screen starting with the current screen level. scrn menu level (1 - 16) mnptr pointer to current menu status buffer