The CIA World Factbook 1992

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

/ The CIA World Factbook 1992 / k3bimage.iso / sel / 04 / 0034 / help.doc < prev next >

Wrap

Text File | 1991-12-02 | 19.3 KB | 388 lines

IBM PERSONAL COMPUTER ON-LINE HELP V5.4 by D.N.Ikle' 03/01/86 For public domain use only DESCRIPTION On-Line HELP provides access to descriptions of all the commands and utilities available on an IBM PC/XT or PC compatible hard disk system under IBM PC DOS 3.x. An abbreviated version can also be installed on a floppy disk based PC or PC compatible system under IBM or MS DOS 2.x. On-Line HELP can be invoked either from the DOS prompt or from within an application program, and it can be easily modified to describe any particular system. REQUIREMENTS The minimum requirements are an IBM PC or PC compatible, a color or monochrome monitor in 80 column display mode, version 2.0 or higher of MS or IBM DOS, and something approaching 64k of free memory. A hard disk significantly improves performance but is not required. The public domain utility DPATH, or its equivalent, is required if the HELP text files are stored in sub-directories. The public domain utility ARC is required to extract the individual files from the distribution files. BACKGROUND HELP accepts 1-8 character keyword input from the user and displays the contents of the text file with the same name as the keyword with the extension .###. Since any useful implementation of On-Line HELP may use at least 60 *.### files, the tree structure feature of DOS 2.0 and higher can be used to more effectively organize these files on a hard disk. However, appropriate paths must be created so that DOS can find the executable HELP file and the *.### HELP text files in whatever directory structure the user has created. Specifically, the DOS PATH command is used to allow non-resident HELP to be executed from any sub-directory, and the public domain utility DPATH, or its equivalent, is used to enable HELP to read the requested *.### text file. Of course, the memory resident version of HELP may be executed from anywhere on the system. FILES On-Line HELP is distributed on bulletin boards in the two archive files HELPxxA.ARC and HELPxxB.ARC, where xx is the current version number. The public domain utility ARC is required to extract the individual files. HELPxxA.ARC contains files needed to install non-resident HELP and to describe IBM DOS 3.1 commands. Included are: HELPxx.TXT Description of version xx archive files. COMMAND1.### Annotated list of IBM DOS 3.1 commands. DPATH.ARC Public domain path extender utility. HELP.### On-Line HELP display file describing HELP. HELP.COM On-Line HELP program (non-resident). HELP.DOC Documentation for On-Line HELP. HELPDOS3.ARC HELP files for IBM DOS 3.1 commands. TEMPLATE Skeleton HELP display file. HELPxxB.ARC contains the memory resident version of the HELP program, additional HELP files that describe the Norton Utilities Version 3.1 and 24 common public domain utilities, and the Turbo Pascal source code for the two versions of HELP. Included are: HELPxx.TXT Description of version xx archive files. COMMAND2.### Annotated list of all commands/utilities. HELP.INC TP include file of common procedures. HELP.PAS TP source code for non-resident HELP. HELPER.### On-Line HELP display file describing HELPER. HELPER.COM On-Line HELP program (memory resident). HELPER.PAS TP source code for memory resident HELP. HELPNORT.ARC HELP files for the Norton Utilities 3.1. HELPPUBL.ARC HELP files for public domain utilities. INSTALLATION Because of the large number of possibilities for different system configurations, the following installation instructions are necessarily very general. They should, however, provide enough guidance to enable anyone to install On-Line HELP on their own system. Both versions require that the display be set to an 80 column mode and that the CONFIG.SYS file open at least 16 files. For the non-resident version: 1. Extract all HELP files from the archive files using the public domain utility ARC. 2. Copy HELP.COM and DPATH.COM to the sub-directory containing your DOS external commands and/or whatever other system utilities you may have. You presumably already have the appropriate path set up to allow you to execute these commands from any sub-directory on the system. If not, you must use the DOS PATH command to create one. 3. Copy the *.### HELP files into some directory structure that is compatible with that already on your system. Delete any *.### files that describe commands not on your system. If your system is under IBM DOS 2.x or MS DOS 2.x, the files supplied for IBM DOS 3.1 will have to be edited. 4. Rename one of the COMMAND?.### files to COMMANDS.### and edit it appropriately so that it lists only those commands actually described in the *.### files you installed. 5. Create an extended data file search path to the *.### files by inserting appropriate SET DP= and DPATH statements into your AUTOEXEC.BAT file. See DPATH.DOC for detailed instructions on how that works. 6. Re-boot the system and begin using non-resident HELP. For the memory resident version: 1. Follow steps 1 to 5 above. 2. Copy HELPER.COM to the sub-directory containing HELP.COM. 3A. Enter HELPER at the DOS prompt to attach On-Line HELP as an extension of DOS. An error message indicates if there is not enough memory or if the user interrupt is already taken. 3B. Alternatively, the statement HELPER may be included in your AUTOEXEC.BAT file, and On-Line HELP will be installed automatically each time the system is booted. 4. Re-boot the system and begin using resident HELP. Once the On-Line HELP facility is running on your system, you can use your own imagination to create other *.### files. For example, I have the additional files SYSTEM.### and NORTON.### that describe my system configuration and list the Norton Utilities, respectively. Note that HELP.COM does not expand tabs, so that any edited *.### file must be saved without tabs. Of course, much of the preceeding is not necessarily useful if you want to install HELP on a floppy-disk based system. In that case, simply cram as much as you can on your system diskette and go for it. Alternatively, you can put all the *.### files on a separate diskette and create a data path to it with DPATH. Both the memory resident and the non-resident versions of On-Line HELP have been tested extensively on a variety of IBM and PC compatible systems with monochrome and color monitors and various assortments of memory resident software. The author is not yet aware of any problems that would preclude the use of either version on such a system. However, if problems are encountered in installing resident HELP, refer to the Maintenance section of this documentation for guidance. If that doesn't help, contact the author at one of the phone or bbs numbers listed at the end of this documentation. USAGE To execute the non-resident version of HELP enter HELP [keyword ... ] where the optional arguments may be any number of 1 to 8 character keywords separated by blanks. For example, HELP Displays a menu for entry of a keyword. HELP ? Displays a brief summary of On-Line HELP. HELP HELP Displays a detailed description of HELP. HELP command Displays HELP for the specified command. HELP feature Displays HELP for the specified feature. Features supplied with On-Line HELP are: AUTOEXEC Special automatic batch file. BATCH Batch file sub-commands. CONFIG Configuration file sub-commands.. FILTERS Processing standard input/output. PIPES Piping output between programs. REDIRECT Redirecting standard input/output. COMMANDS Annotated list of all commands. HELP keyword ... Displays the HELP file for each requested command or feature in sequence. Once installed, the memory resident version of HELP is executed by pressing Ctrl-F1 at any time. This is equivalent to executing the non-resident version with no keywords on the command line. Ctrl-F1 may not be pressed twice in succession, and if it is, a two tone sound is emitted by the speaker, and nothing else happens. Both versions are entirely compatible and, in fact, may be executed simultaneously. Keywords can be entered in either upper or lower case. Entry of HELP with no keywords displays a keyword entry menu in which keywords may be entered into an eight character keyword entry field. In addition to character keys allowed in DOS filenames, the following keyboard keys are available: Left Moves cursor one character to the left. Right Moves cursor one character to the right. Home Moves cursor to the beginning of the field. End Moves cursor to the end of the entry. Insert Inserts one blank character at the cursor. Delete Deletes the character over the cursor. Backspace Deletes character to the left of the cursor. Escape Erases the current entry. Enter Displays HELP for the current entry or quits. ? Displays brief instructions in using HELP. Pressing any other key produces a soft speaker tone. Press Enter to display HELP for the current keyword entry. Entry of an invalid keyword on either the command line or on the keyword entry menu produces a loud speaker tone, and the entry menu is displayed with the invalid entry to be edited. By definition, an invalid entry is one for which the corresponding file with extension .### does not exist in the current data file path. Keywords entered on the command line are described in sequence with interruptions by the entry menu as invalid entries are encountered. Pressing Enter while the entry field is blank either returns to processing of command line entries or, if there are no such entries outstanding, to the operating system at the point where HELP was invoked. Following acceptance of a valid keyword, up to 8 pages of text (23 lines each) are displayed from the file that describes that keyword. On any HELP screen, the following keyboard keys are available: Up Scrolls the file up one line. Down Scrolls the file down one line. Page Up Scrolls the file up one page. Page Down Scrolls the file down one page. Home Displays the first page in the file. End Displays the last page in the file. Enter Returns to entry menu or next HELP request. Escape Returns to the operating system. Pressing any other key produces a soft speaker tone. The bottom line of the display summarizes these functions and indicates when the end of the file has been reached. Pressing Enter returns control to the keyword entry menu or returns to processing of command line entries if any such entries are outstanding. Pressing Escape returns control to the operating system. In the non-resident version, the last HELP screen remains displayed and the cursor is placed on the bottom line of the display. In the memory resident version, control is returned to the operating system at the point where Ctrl-F1 was pressed. NOTATION The notation used in the *.### files to describe the correct command syntax is compatible with that used in the IBM DOS manuals, except that the vertical bar used by IBM to indicate "or" is replaced by !. In particular: Keywords are given in capital letters, but may be entered in either case. Words in lower case must be substituted for as described in the remarks. Items in square brackets ([]) are optional. Do not enter the brackets. Items separated by a ! means that you enter one or the other, but not both. An ellipsis (...) means that the preceeding item may be repeated. Punctuation other than [] and ! must be included as shown. d: denotes a drive, either fixed or floppy. path denotes a sequence of directory names (<64 characters) filename denotes a disk file name of 1-8 characters. .ext denotes an optional file extension of 1-3 characters. filespec denotes a file name of the form filename.ext The global filename characters are ?, which indicates that any character can occupy that position, and *, which indicates that any character can occupy that and all remaining positions in the filename or extension. Note that beginning with IBM DOS 3.0 all external commands may be preceeded by a drive and path specification. MAINTENANCE The individual *.### HELP displays are ASCII text files that may be easily edited using any text editor. Most displays have been kept to one screen for simplicity, but some are longer to describe certain commands or features. The maximum allowable length of a *.### file is 184 lines (8 pages of 23 lines each) of 80 column text. A skeleton HELP file is provided in the distribution archive files to assist in the creation of new HELP files. Note that HELP does not expand tabs, so that any *.### file that is edited must be saved without tabs. Installation of the memory resident version of HELP can be particularly challenging if other resident programs are also installed and they conflict in some way with resident HELP. In that case, the first option is simply to try installing your resident programs in different orders until you find a sequence that eliminates interference between the programs. If that doesn't work, you may need to recompile HELPER.PAS using Turbo Pascal Version 3.0 or higher and at least $0200 paragraphs of dynamic memory. The memory resident procedures use the two variables our_char and user_int to define the scan code of the calling key sequence and the number of the user interrupt that monitors the keyboard, respectively. They are initialized to 94 (Ctrl-F1) and and $64, respectively, and either may be changed as desired. Also, if you don't want to use the extended data path capability of DPATH, the variable file_name in procedure input_menu can be set to include a specific path to the *.### HELP files. If significant improvements are made to the program or if *.### files are created that would have wide appeal, please send them to the author at the bbs number listed at the end of this documentation. If I agree, I will include them in future releases of On-Line HELP. HISTORY On-Line HELP started out as a programming exercise in BASIC and has evolved into a stimulating educational experience in Turbo Pascal. I have also found it invaluable in my efforts to keep the clutter around my XT to a minimum. Version 5.0 incorporates numerous improvements that enhance program function and speed its execution. For example, the instruction screen is stored internally as an array, the heap is used to save and restore the initial display screen, all writing to the screen is done through the screen buffer, and the keyword entry field on the main menu has full editing capability. Version 5.1 blanks the cursor when HELP screens are displayed and displays the menu and HELP screens in color on a color monitor. Version 5.2 includes a memory resident version of the program that allows HELP to be invoked from within other programs. The distribution files have been renamed to show the current version. Version 5.3 adds a separate HELP file for HELPER and changes the keystroke sequence to execute HELPER from Alt-F1 to Ctrl-F1. Version 5.4 is archived using ARC Ver 5.12 to save more space, and the public domain HELP files have been revised somewhat. ACKNOWLEDGEMENTS This program relies on another public domain program DPATH, by James A. McGreggor Jr., that allows HELP to function in its current design. It is a very useful utility that fills a major void in IBM/MS DOS and it should be a part of any hard disk system. In addition, the following public domain Turbo Pascal procedures are used in the program: FASTWRITE is an inline routine, by Marshall Brain, that writes text to the screen very quickly through the video memory; a set of procedures by Brenston Worrell was adapted to implement the editing capability of the keyword entry menu; two procedures that remove and restore the cursor were adapted from an article by Mark Brown in TUG Lines, the journal of the Turbo User Group; a set of procedures by Lane Ferris, called Stayres Version 3.2C, attaches the resident version of HELP as an extension to DOS, thereby making HELP available from within other programs. SOURCE This utility is placed in the public domain by its author and is dedicated to the continued growth of public domain software. Comments and suggestions are welcomed. Messages may be left on the Denver_Fido 104/56 303-973-9338. Copyright 1985,1986 by David N. Ikle'. All rights reserved. David N. Ikle' 1671 Newport St. Denver, CO 80220 303-333-9322 (voice)