\tMain Menu. Main Menu: 1) Create help file 2) Read records from help file 3) Read help file by topic 4) Get help 5) Display disk directory 6) Reset disk drives 7) Rename files on disk 8) Kill files from disk 9) End program Your choice: \tPurpose of this program. Purpose of this program. The purpose of this program is to provide you, as a BASIC programmer, with a simple way to produce help files to accompany your programs. This is done in a three step process: 1) Write the help screens you want, using WordStar or any other popular word processing program that stores files in normal ASCII. 2) Convert the file you wrote in Step 1 to a random access file. 3) Install a simple random-file reader subroutine in your BASIC program that asks which topic number you want, and then call that screen up. Your help files are topic oriented, with each topic capable of spanning several screens. The length of each screen, the number of screens and the number of topics are set by yourself. Your only limitations are that you may not exceed 100 topics (an arbitary limit which may be altered if necessary) and that your entire file may not exceed 32766 lines. This last limitation is imposed by Microsoft BASIC. \tPreparing your input file. Preparing your input file. The secret to writing your input file is the use of the topic and screen delimiters. These are the reverse-slash, followed by the letter 't' to mark the beginning and ending of each topic, and reverse-slash, followed by the letter 's' to mark the end of each screen. These must be in the first two postions on a new line to have effect. Example: \t --> marks the beginning and ending of a topic. \s --> marks the ending of a screen. Up to 48 characters may immediately follow the '\t' to give a title to the next topic. Any characters following the '\s' are carried over to the resulting file, but these lines are never printed. This would be one way to make comments about screens. Another (better) way is to just start a line with a reverse-slash, followed by any letter than 't' or 's'. These are comment lines that will be retained in the final file, but never printed. \s Preparing your input file. Boot your word processor program, and set the right margin to no more than 78 characters. This is the maximum line length the program can accept. Enter a reverse-slash plus the letter 't' in the far left hand side of the first line to mark the beginning of the first topic. If you like, you can give this topic a title, which your own program can read later on. To do this, enter the title in the next 48 spaces immediately following the '\t'. For example, the input file for this topic began like this: \tPreparing your input file. This line will be placed in a reserved area in the front of the resulting file. Specifically, if this were the third topic, it would be placed in the third record, along with a pointer to the first valid record and the number of following records which relate to the same topic. \s Preparing your input file. Type the first screen as you want it to show to the user, with each line ending in a carriage return. When you are all finished writing your first screen, enter a reverse-slash and the letter 's' at the beginning of the next line. This will mark the end of the first screen, and the beginning of the second. It would look like this: \s Just repeat this process for each screen you want to write for the current topic, until you have written each screen. The final result of this will be a series of screens, each separated by the '\s' characters. If you are through with the topic you were writing about, enter a '\t' instead. This will indicate the beginning of the next topic. Of course, you will probably want to give this next topic a title as well. When you finish your final screen, enter one last '\t' at the beginning of the very last line. This will mark the end of the file. \s Preparing your input file. To recap: 1. Load your word processor. Use one that stores its files in straight ASCII. WordStar does fine for this, but use the 'N'on-document mode, or use a filtering program such as FILT7.COM before you run TXT2HLP.BAS. 2. Set your right margin to 78 or fewer characters per line. 3. Enter the characters '\t' at the far left side of the first line of the file. You may put a title for the first topic in the next 48 spaces. 4. Write your screen. When you have finished that screen, enter '\s' on the far left of the next line. Your program later will see this as the end of a screen, and pause. 5. When you have finished with a topic, and want to go onto a whole new topic, enter a '\t' instead of '\s'. Your program will pause when it reaches the point marked by this, and return to your main program. You should enter the title of the next topic just as you did in step 3. 6. Enter '\t' at the end of the file to mark its end. 7. Save this file. \s Preparing your input file. Some notes: 1. Be SURE you have a carriage return at the end of each line before saving your input file. This is the one way to crash this program, with a 'STRING TOO LONG' error. If you used WordStar in the 'D'ocument mode, you must run a filtering program such as FILT7.COM on the file prior to using TXT2HLP.BAS. 2. The letters 't' and 's' can be in either upper or lower case. 3. Any line starting with a reverse-slash mark will not be displayed. If you want to show a line starting with this character, put a space in front of it. However, such a line WILL be put into the resulting file, and can be used for imbedded comments. Avoid having the letter 'p' immediately after the reverse-slash, as this is reserved for a future command. 4. If you are writing a very long and involved program, consider putting your command menus in your help file. It will save considerable memory. \s To help you see how the input file is made, the source file for this help file has been included with the library I have distributed the program in. \tCreate help file. Create help file. This is the first choice in the menu for this program. It takes a text file which has been previously written with a word processor, and converts it to a random access file in a particular format. Load and run this program, and select option 1. You will be prompted for the name of the file you created with the word processor, and then the name of the file you want to create as your help file. The rest is automatic. This program will read through the input file, calculate how many topics you have declared, and reserve one record for each at the beginning of the resulting output file. \s Create help file. The reserved records at the beginning of the file are the pointer records. These will show where each topic begins in the output file, and how many lines long it is. Therefore, all your BASIC program needs to do is to open the help file for random access, with a record length of 78, and GET the record number corresponding to the topic number you want. You will get two numbers from this record: The record number for the first line of the first screen of the topic you want, and the number of lines following that belong to that topic. Now all your program needs to do is get that first line, print it, and loop back the number of times as you have lines to read/print before RETURNing to the calling routine. Each time it loops, it should check for the occurrance of a reverse-slash mark followed by the letter 's' in either upper or lower case. This marks a screen break. At this point, your program should pause, and allow the user to abort the file read by entering a 'Q'. \tRead records from help file. Read records from help file. This is the second option in the main menu. You will be asked for the name of the file you want to read. If your file is not a random access file, the read will abort, and you will return to the main menu. You can use this option to see how your file has been constructed, or to read imbedded comment lines which you put in by having lines starting with a reverse-slash mark followed by other than the letters 't' or 's'. Enter a 'Q' to quit at any time, and return to the main menu. \tRead help file by topic. Read help file by topic. This option allows you to choose which topic in your help file you wish to read, or to read the entire file. You are prompted for the name of your file. \tGet help. Get help. This option gives you a choice of topics and displays the file you are now reading. Its internal structure would be excellent as a help file reader for your program. A program listing in MBASIC is given under the help topic 'How to use help files.' \tDisplay Disk Directory. Display Disk Directory. Self explanatory. You are asked for the name of the files you want to see. Enter an asterick ('*') to see all. \tReset disk drives. Reset disk drives. Self explanatory. Be sure to use this option when changing disks. Start this option with the old disks in the drives. You are prompted when to change disks. This will prevent spoiling your disk directory. \tRename files on disk. Rename files on disk. You are prompted for the 'input' (old) and 'output' (new) file names, and asked to confirm your entries. The 'input' file will be given the 'output' name if you agree. \tKill files from disk. Kill files from disk. You are prompted for the name of the file you want to kill, and again prompted to confirm your intention. \tEnd program. End program. Always use this option to end a session with this program. It resets all the drives prior to ending, to assure that all open files are closed, and that the directories are updated. \tHow to use help files. How to use help files. Once you have made your help file, you will need a way to use it from your program. All you need to do is to include the following subroutine, and allow an option at all points for user input for 'help'. The Xerox 820-II has a 'HELP' key, which returns a CHR$(30). This seems to be a natural way to impliment the idea. The only caution is that once a user has asked for help, he will likely need to see the screen in the main program again where he had selected HELP. Also consider the idea of putting all your program menus in this file. It will clear considerable space from your main program, allowing either larger arrays, more complex programs, or at the least, faster operation. The file reader listing follows. \s Help file reader: 25000 INFILE$="filename.ext": OPEN "R",1,INFILE$,78: FIELD #1, 78 AS TXT$: FIELD #1, 5 AS SNUM$, 5 AS SLEN$, 48 AS STOPIC$ 25010 X=1: PRINT CHR$(26): PRINT "Help is available for the following topics:": PRINT: GET#1,X: WHILE VAL(SLEN$) > 0: PRINT RIGHT$(STRING$(2,32)+STR$(X),2);") ";STOPIC$: X=X+1: GET#1,X: WEND \S Help file reader: 25020 PRINT BELL$: PRINT "Enter number beside topic you wish help on, or 'Q' to quit. ";: IN$=INPUT$(2): IF IN$="Q" OR IN$="q" THEN 25100 25030 IF VAL(IN$)<1 OR VAL(IN$)>X THEN 25020 ELSE X=VAL(IN$) 25040 GET#1,X: Y=VAL(SNUM$): Z=VAL(SLEN$) 25050 PRINT CHR$(26): K=Y: WHILE K