 17   16  Main Menu.                                                           33   18  Purpose of this program.                                             51   99  Preparing your input file.                                           150  30  Create help file.                                                    180  11  Read records from help file.                                         191  5   Read help file by topic.                                             196  6   Get help.                                                            202  5   Display Disk Directory.                                              207  5   Reset disk drives.                                                   212  5   Rename files on disk.                                                217  4   Kill files from disk.                                                221  5   End program.                                                         226  75  How to use help files.                                               301  15  Future Enhansements.                                                 316  16  Credits.                                                             332  00  End of file.                                                                                                                                                         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:                                               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.                                     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.    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'.                  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.                 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.                                                                         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.'                                                      Display Disk Directory.                                                                                                                                     Self explanatory.   You are asked for the name of the files you want to see.                                                                                Enter an asterick ('*') to see all.                                           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.                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.                                                            Kill files from disk.                                                                                                                                       You  are  prompted  for the name of the file you want  to  kill,  and  again  prompted to confirm your intention.                                           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.                                             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<Y+Z:                                                                          GET#1,K                                                       \s                                                                            Help file reader:                                                                                                                                           25060           IF LEFT$(TXT$,2)="\S" OR LEFT$(TXT$,2)="\s"                                           THEN    PRINT CHR$(7):                                                                PRINT "Any key to continue, or 'Q' to quit.";:                                IN$=INPUT$(1):                                                                IF IN$="Q" OR IN$="q"                                                                 THEN    25100:                                                                ELSE    PRINT CHR$(26):                                                               GOTO 25090                    25070           IF LEFT$(TXT$,1)="\"                                                                  THEN    25090                                         25080           PRINT TXT$                                                    \s                                                                            Help file reader:                                                                                                                                           25090           K=K+1:                                                                WEND:                                                                         PRINT CHR$(7):                                                                PRINT "End of topic.  Any key to continue. ";:                                IN$=INPUT$(1)                                                         25100   CLOSE:                                                                        RETURN                                                                                                                                              Future Enhancements.                                                                                                                                        This  program is pretty much a finished product.   I would like to include a  way  to  have  a 'prompt' line,  which would display an input  prompt  at  a  specified  place on the screen.   The file read subroutine would have to  be  rewritten to allow for this.                                                                                                                                I  have also not come across a way to display the free space remaining on  a  disk without resorting to machine code.  I want this entire program to be in  BASIC, to assure its transportability.  I would appreciate a tip on this!                                                                                   Lastly,  I have not put in all the possible error codes in the  program,  to  allow a more orderly handling of such things as disk full errors, etc.                                                                                      As for other enhansements, I'm open to ideas.                                 Credits.                                                                                                                                                    This utility was written in June 1987 by:                                                                                                                                            LEE MCEWEN                                                                    2426 Stone Haven Court                                                        Orange Park, FL  32065                                                                                                             (c) Copyright 1987, 1988. All rights reserved.                                                                                                              Non-commercial use and distribution authorized subject to limitations as set  forth in program source code.                                                                                                                               I may be contacted on GEnie, under mail address: C.MCEWEN.                                                                                                  Hope you find use for it.  Let me know how things went!                       