High Voltage Shareware/high1.zip/high1/DIR3/FR20.ZIP/HELP

Text File | 1994-02-01 | 32KB | 643 lines

.

                                 HELP File for

                              FRANK'S READER - V20

                       Copyright (c) 1994, Frank F. Yates


         This file contains a detailed description of every command and
         parameter used by Frank's Reader (FR). It is designed primarily
         as an on-line reference, but may also be useful as a tutorial
         for new users.


                       Use Up/Down arrows to scroll text.

                    Use Right/Left arrows to select sections.

                    Press F1 to see the full set of commands.




.Getting Started

   To learn about the Reader, I suggest that you use the Reader itself to
   examine this file, and test out each feature as it is explained here.
   To start the Reader, go to the directory where the HELP file is located
   and start the reader on it: FR HELP      (R HELP if you have renamed it)

   The first thing you might want to do in the Reader is to press F1 and
   study the Command List that will be displayed. This list is hard coded
   in the program and is always available for reference except when the Reader
   is asking you for something specific, such as a file name or a mark
   definition. To exit the Command List, press F1 again, or any other key.
   When the HELP panel is displayed, a Key-Press is not interpreted as a
   command, but just returns you to wherever you were before.

   The next thing you might want to take a look at is the Parameters Menu (P)
   to see what is available there, maybe experiment with the colors. Then
   continue reading the HELP file to the end.

   Press Enter to see the Module List, and then the Down Arrow to read more
   sections (modules) from the help file. Then select a section of interest
   by pressing Enter again. When in doubt, press F1 for Help.

.
.Details of Reader Commands

   Each of the Reader commands has a separate section following this one.
   That is to make this file a convenient on-line reference. If you need
   quick information about a particular command or parameter while you are
   using the reader, just open the HELP file and scan the list of Headers
   to pick out the section you want, or use a Find command (f or F2).

   Most of the Reader commands are "Hot Keys"; just touch the key and
   get immediate action. The main exception is the DOS command prefix ".".
   That will get you a flashing cursor, at which you can type in a DOS
   command and press Enter to execute it. If you just press Enter after
   the "." without any command, then you will be put in the DOS command
   loop and can execute multiple commands. When you are done, enter
   "exit" to get back to the reader.

   Normally you won't see a cursor anywhere on the Reader screens.
   This is because you are only going to touch one key at a time, and you
   don't need a cursor. If you DO see a cursor flashing somewhere, that is
   a signal that you are expected to enter a line of something and then
   press Enter. This will happen when you have been asked a question, and
   the answer might be more than one character long.

.
.-----Letter Keys

.A             Save all modules

   The "A" command writes all modules in the list to the currently open
   output file. If no output file is open, you will be asked for the name
   of one to open.

.D             Delete a module

   The DELETE key or the letter "D" will delete the currently selected
   module. It deletes the selected module from memory. It does not affect
   the input file, only Reader's working storage. If you want to delete all
   the current data and start with a clean slate, press END instead.

.E             Edit a module

   The "E" command allows you to edit a module in memory. This does not
   affect the input file, but you can easily save a collection of edited
   modules to a new file, replacing the original file, or while in the
   editor you can work with the module contents in whatever way you wish.
   The command works by copying the module to a temporary work file,
   invoking your editor, then replacing the module in memory with the
   contents of the edited file. You can specify both the editor to be
   used, and the name and location of the work file as parameters in
   FR.PAR.

.G             Remove and hold a module

   This command gets a module from the list and puts it on "Hold". The "H"
   command re-inserts the held module into the list. The G and H commands
   together provide an easy means of re-arranging the list of modules,
   because you can pick a module up from one location and put it back in
   another.

.H             Insert a "Held" module into the list

   This command re-inserts a previously held module into the list after the
   current location.

.I             Select or Change the INPUT file

   When you press "I" the Reader will close your present input file (if any)
   and list the files in the current directory. You will then be asked to
   enter the name of the file you wish to open. Entering a null line at this
   point aborts the input request. If the file you want is not in the
   current directory, you may include the path to a different directory.

   More elaborate directory operations are not provided within the (I)nput
   command, but from the List or Text mode displays you may enter direct
   DOS directory commands with all the options, and you may change the
   active directory also when desired.


.K             CLOSE the Input File

   This command is provided so that you can close the input file prior to
   deleting it, or performing some other operation inconsistent with an
   open file. It is usually possible to shell out to an editor and modify
   the input file without closing the file from FR, however you should limit
   your next action to scratching the list and re-reading the file
   (END + HOME). Attempting to continue reading in a modified input file
   may have unpredictable results.

.L             CLOSE the Output File

   This is another shortcut key. In previous versions of FR it was necessary
   to press "O" (for specifying an Output File) and then entering a null
   line for the file name in order to close the output file. The "L"
   hot-key makes closing the output file easier.

.O             Select or Close the Output File

   The "Output" file is the one the Reader will write to when you issue a
   Save command (press the letter S). Its name is displayed on the right
   side of the top line of the Selection List. You may change this file any
   time by using the "O" command.

   The first action taken when you issue "O" is to close the current output
   file. This is required prior to opening a new output file. If you only
   want to close the current output file but not open a new one, enter a
   null line when the Reader asks you for the file name. Closing the file
   flushes the most recent lines out of memory and releases the file. This
   is necessary to do if you are going to read or write to that file with
   another program.

   The output file (if any) is closed automatically when you exit the reader
   normally (Esc), so you need not think about closing it unless you are
   accessing it via DOS commands while the Reader is still running.

.P             Parameters

   Frank's Reader has a number of parameters controlling its operation
   which you can adjust according to your needs and preferences. This may
   be done on-line thru the Parameter Menu (P), and the start-up values
   can be specified in the parameter file "FR.PAR". Be sure to read
   about FR.PAR in "READ.ME". There is also information about parameters
   in the FR.PAR file itself, which is an ordinary text file.

   The effect of parameters entered on-line or via FR.PAR is the same
   for every parameter except "MARK". On-line setting a value for MARK
   has immediate effect, whereas the FR.PAR file has multiple MARK
   definitions, forming a list from which FR recognizes marks in new
   input files.

.R             Resource Report

   This command displays the current state of resource usage. Two items
   are included, Lines, and Nodes.

   Storage of lines requires string space, of which there is a limited
   amount. The longer the lines, and the more of them, the more string
   space is used. FR counts the number of lines actually stored, and
   estimates the number of additional lines which could be stored if
   they were each 80 bytes long. This will be a conservative estimate
   unless lines longer than 80 characters are frequent in the data.

   Data and various other things are managed within FR by linked
   lists. Such lists require nodes, which are obtained from a node
   pool of fixed size. The number of nodes in the pool is an FR
   parameter (NODES). In computing the Resource Report FR counts the
   number of free nodes left, and compares that with the number which
   were originally allocated.

   One or the other of these two resources may be critical, depending
   upon the characteristics of the data being processed. If there are
   a lot of long lines, then string space (lines) will run out first.
   If there are a lot of short lines, then nodes will run out first.
   Depending upon which type of data you are processing, you may want
   to increase or decrease the number of nodes allocated. Having fewer
   nodes will create more string space. The initial value of NODES is
   1400, a number which has been found to work well for most data.

.S             SAVE the selected module

   Pressing the letter "S" saves the currently selected module to the
   current Output file. You may issue this command while you are looking
   at the Selection list, or while looking at text. Saves are always added
   to the end of files if they exist, and never overlay data.

   The output file name is displayed on the top of the Selection List. You
   can select, change, or close the output file by the "O" command. If you
   have not selected an output file prior to issuing a save command, the
   Reader will ask you at that time for the Output file name.

   After a module has been saved, that fact is indicated by a letter "S"
   in column 80 of the module list.

.
.-----Special Keys

.Esc           Exit the Reader

   This is the command for exiting the Reader. Remember it, because there
   is no other good way to quit. There is a safety check to guard against
   premature accidental exits. The first press of Esc produces a message
   "Quit Now?". Pressing Esc again, or the letter "Y" will terminate the
   program. Any other key will abort the exit.

.F1            HELP

   Many programs these days use F1 to summon on-line help, so Reader does
   too. What you get in this case is a short list of the commands, sort of a
   reminder list. If this isn't enough at the time, open this Help file and
   read the more detailed explanations which are here.

   You may press F1 again to return to where you were, or any other key.
   Commands are not accepted from the HELP screen.

.F2            Find selected text

   In response to Function Key F2 (or the letter "F"), the Reader will ask
   you for a string to search for. It will then look for your string from
   the top of the current text display to the end of file. The search is not
   case sensitive; ie. any mixture of capitals and lower-case letters will
   be matched. The search string may contain any printable character and/or
   blanks, leading, embedded, or trailing.

   When a match is found, the module containing the match is selected, and
   the text of that module is displayed with the found string on the top
   line. The header line will be displayed as a message on line 23 of your
   display. This will the currently active relative line (1-9) which is
   displayed in the module list and which is selected by you via the number
   keys 1-9. Since Find displays the found string at the top of the page
   instead of line 1 of the module, this message may be helpful in
   identifying the module. Of course you can always Page-Up to the top of the
   module if you like.

   If the string is not found in the loaded modules, then all loaded modules
   will be scratched and the rest of the input file will be searched. If
   the KM (Keep Modules) flag is set, FR will ask your permission before
   scratching modules.

.F3            Repeat find

   The Repeat Find operation is identical to the Find operation except that
   you are not asked to define the string, and the search begins on the
   line following the current line (ie. line 2 of the text display).

.F8            Toggle the KM (Keep Module) Switch

   This is a convenient way to change the KM Switch without going to the
   Parameter menu and entering KM, KM=Y, or KM=N. If you are looking at
   reference data which will not be processed in any way, then you will
   probably want to permit modules to scroll off the top of the list
   (ie. KM=NO). If you are processing the modules however, likely you
   will want to have KM=YES so that you do not miss any.

.1-9           Header Line Selection

   The number keys 1 thru 9 may be used to control the number of the header
   line which is displayed in the LIST mode. When the data consists of
   messages or other modules with a multi-line header structure, this
   feature will be immensely helpful because it will allow you to select a
   particular line from the multi-line header to display in the selection
   list. Thus you can see a list of senders, addressees, subjects, dates,
   message numbers, or whatever aspect of the message set interests you at
   the moment. Be sure to try this feature of the Reader on a file of
   messages.

.Home          Rewind the Input File

   The HOME key rewinds the input file. This has no immediate effect on the
   display, except that the file will be rewound and you will see a message
   on line 23 to that effect. The next module to be read from the file will
   be the first. This does not affect the loaded data at all.

   You are probably wondering how to move the text display back to the top
   of a module. The easiest way to do this is to press first the
   right-arrow and then the left-arrow, or vice-versa. If you press ENTER
   twice, text will stay in the same place, but you get to look at the List
   during the trip.

.Page-Up       Go to top of List, or view previous page of text

   In List mode the Page-Up command flushes the loaded modules and
   reloads the list from the beginning of the file.

   In Text mode, the Page-Up command displays the previous page of text.

.Page-Down     Load the next set of modules, or view the next page of text

   In List mode the Page-Down key flushes the loaded modules and loads
   the list from the next modules in the input file. If KM is set,
   Page-Down cannot flush modules, but if the list is empty (such as
   when you press END first), Page-Down can still re-load the list.

   In Text mode the Page-Down key displays the next page of text.

.Delete-Key    Delete a module

   The DELETE key or the letter "D" will delete the currently selected
   module. It deletes the selected module from memory. It does not affect
   the input file, only Reader's working storage. If you want to delete all
   the current data and start with a clean slate, press END instead.

.End-key       Delete all data in memory

   This will completely erase your list of data modules. It does not affect
   the input or output files. This command is useful in at least the
   following three circumstances.

   * If you are about to switch to an unrelated input file and want to clear
     out the old data.

   * If you have looked at everything on the list and want to read new data
     into an empty screen.

   * If you are running short of string space, perhaps causing the reading
     of new data to stop. Pressing the END key is a quick way to free up
     lots of space.

.Up Arrow      Select previous module, or scroll up text

   In List mode the UP arrow key selects the next higher module in the
   list. At the top of the list it stops because FR does not read
   backwards in the file. To see an earlier module, press HOME to
   rewind the file and continue forward to the desired place.

   In Text mode the UP arrow key simply scrolls the text display.

.Down-Arrow    Select next module, or Scroll down text

   The DOWN arrow key is used in both in List mode and in Text mode.
   In List mode it selects the next lower module in the list, and at
   the bottom of the list causes another module to be read from the
   input file. In Text mode it simply scrolls the text down.

.Left-Arrow    Display Text of the Previous Module

   The Left Arrow key, when in text mode, jumps to the previous module.
   It will only go back as far as the top of the selection list. To go
   backwards further in the file, you need to rewind (Home Key).

.Right Arrow   Display Text of the Next Module

   The  Right Arrow key, when in text mode, jumps to the next module.
   This is the fastest way to scan thru a file if you want to take a
   quick look at everything rather than selecting modules from the list.

..command      Execute a DOS Command

   From either the LIST or the TEXT displays you may issue commands directly
   to DOS by prefixing them with a period ".". When you press the period
   key, a cursor will appear in the System Message area at the bottom of the
   screen. At that point the Reader is expecting a DOS command line, and an
   Enter when it is complete. The command you enter will be executed and
   control will then be returned directly to where you issued the command
   from. If you enter just the "." with no command specified, you will
   "Shell" to the DOS command interpreter, where you can perform complex
   operations involving multiple DOS commands. When you are ready to return
   to the Reader, enter "exit" at a DOS prompt.

.Enter         Toggle between List and Text Displays

   The Enter key is a Hot Key most of the time for the Reader. If you
   do not see a flashing cursor at the bottom of the screen, then touching
   the Enter key will produce instant action. It will swap the display
   from the selection List to viewing text of the selected module, and
   vice-versa.

   I you do see a flashing cursor, then FR is expecting a line input
   from you, which may be one or more characters long depending upon
   the context. Text may then be entered as on a command line, and
   backspace may be used to make corrections. When your line entry
   is finished, pressing Enter will begin the operation on your entry.

.>             Shift Text Window Right

   This command lets you see the ends of lines which are longer than
   80 columns.

.<             Shift Text Window Left

   This lets you look more toward the beginning of lines after using
   the ">" command.

.Space Bar     Read input or Scroll Text

   Pressing the SPACE bar scrolls the module list or the text of a module,
   depending upon whether you are in LIST mode or TEXT mode. While you
   hold the bar down, data will scroll, and when you release it the
   scrolling stops. This is a change from previous versions of the
   reader. It gives you easier control and requires less work than the
   previous design.

   In List mode, new modules are read into the bottom of the list, and
   old modules may scroll off the top of the list (if the KM switch is off).
   In text mode the end of the module data is indicated by: ---end---.

.
.-----Reader Parameters

   Various aspects of FR can be controlled on-line via parameter settings.
   These are reached via the "P" command, and for colors, via a "C"
   command from the parameter menu. All of these parameters may be
   (and in many cases _must_ be initialized via the FR.PAR parameter file.
   Some things, such as Editor selection, can only be controlled by
   values in the FR.PAR file.

   The easiest way to select parameter values for your use is to test
   them on-line via the Parameter Menu. When values are found which
   satisfy, then shell out of the Reader to your editor and change
   the defaults in FR.PAR. The changed values will then be the new defaults.
   Notice that the Parameter Menu has a secondary menu for Color adjustment
   which is accessed by "C". This one includes a display of all the
   available colors, so you do not have to look up the meaning of the
   various color numbers.

   All parameters are specified in Keyword form (Name=Value). Some are
   numerical, and some are logical (Yes/No), which may be specified as
   Y or N if desired. Logical parameters may also be reversed on-line
   by just entering their name from the Parameter Menu. For example,
   if the Automatic Mark Recognition flag is "YES", you may change it
   to NO by just entering "AM".

   Additional information and instructions can be found as comments in
   the FR.PAR file.

.AM=Y/N        Automatic Mark Recognition

   If Yes, the first line of each input file is examined to see if it begins
   with one of the default Header Marks. If so, that mark becomes the active
   Mark for the file. If the AM Flag is No, then the current Mark (whether
   set automatically or manually) remains in effect until changed manually
   or until the AM Flag is set to Yes and a new file is opened. The
   automatic mode is probably the most useful, but there are times when it
   is desirable to control the mark manually. At such times, turn the AM
   flag off.

.COLORS        FC, BC, HFC, HBC, MFC, MBC, SFC, SMC

   There are eight color options that you may choose for the Reader Display
   The colors are controlled by numbers.

   You don't have to memorize the color numbers or look them up because the
   actual colors are displayed with the numbers on the PARMS menu. What you
   see is what you get. Foreground colors may be in the range of 0 to 15,
   and background colors in the range 0 to 7. The background colors 8 thru
   15 are duplicates of the colors 0-7, but for foreground colors you get 16
   different choices.

   The color symbols that you may assign numbers to are the following;

   FC, BC    List or Text display, foreground and background
   HFC, HBC  Highlighted (selected) items, foreground and background
   MFC, MBC  Menus, foreground and background
   SFC, SBC  System message colors, foreground and background

.EDITOR=name   Name of your text editor

   This is the editor which is invoked by the "E" command to edit a module.
   If it is not located in your execution path, then a sufficient path
   should be specified as part of "name".

.EDFILE=file   Name of the work file where modules are edited.

   FR will write a module to this file and invoke your editor. You then
   edit the module and save it. When you exit your editor, FR reads the
   revised file back into the list, replacing the original module. If you
   have a virtual drive, that would be a good place for this file, but
   any valid file path and name will do.

.ENDMARK=mark  Mark which denotes the end of a module

   In some kinds of modular files, particularly BBS messages, there is
   often junk following the end of a message consisting of control
   commands and system prompts. There is often an end-of-message mark
   however, such as "<<<>>>". When such marks exist, FR can now recognize
   them and terminate input modules when these marks are encountered.
   If no such mark exists, set ENDMARK to null, in which case the test
   is not performed.

.KM=Y/N        Keep Modules

   The "Keep Modules" switch ("Yes" or "No") determines whether or not data
   modules can be scrolled off the top of the list. If you are just looking
   thru reference data it is convenient to have them scroll off, but if you
   are processing a file and don't want to miss anything, then you want
   this switch off. The state of this switch is indicated by the letter
   "K" in column 80 of the List Header if modules are being kept, or a
   blank there if not.  Function key F8 toggles this switch.

.LL=n          Length of the Selection List

   This parameter limits the number of modules which will be loaded at once,
   and therefor the length of the Selection List. The valid range is 1 to 19.
   See comments near the end of this HELP file regarding long modules.
   It is useful when dealing with files containing very long modules.

.MARK=mark     Select the current Header Mark

   The "Header Mark" is the character or characters which are used by the
   Reader to identify the beginning of a new data module. When it finds the
   Mark at the beginning of a line of text, it knows that that the previous
   module has ended and a new one has begun. The marks are entirely
   arbitrary, you may choose anything you wish, and they may vary from file
   to file. It is only necessary that in any one file the selected mark does
   not appear at the beginning of any line which is not a header. A Mark may
   contain special characters, small letters or capitals, numbers, and
   blanks (leading, trailing, or embedded). On the PARMS Menu the current
   Mark is displayed between two angles > < so you can tell where the blanks
   are, if any.

   When the Reader opens a new input file it searches its list of default
   marks (which you gave it in your Parameter file, FR.PAR) to see which one
   corresponds with the beginning of the first line of the new file. If it
   finds a match, it will use that mark for that file, and you will never
   hear about it. If the Reader does not identify a mark, it will display a
   few lines from the new file and ask you to tell it what Mark to use.

   Aside from the above, you may change the active Mark at any time on the
   Parms Menu. You might want to do this, for example, if you had two or
   more different sets of marks in a file to demark different groupings of
   the data. It is possible to read a variety of modules into the list using
   different marks. Once a module has been loaded, the identification mark is
   no longer pertinent since the data management structure defines the
   boundaries of each module.

.MORE=n        Length at which input modules are split

   "MORE" is the length at which input modules are split into parts. This
   is provided to make handling very long modules more convenient, and
   to avoid exceeding FR's storage space. It also makes possible the
   reading of text files which are not structured at all. FR simply
   divides such files into synthetic modules of length "MORE". Each new
   part begins with a special header line consisting of just the MARK and
   "+". This convention makes the List easy to read, and if the modules
   are re-combined in an output file, the inserted headers are unobtrusive
   and easy to find.

   "MORE" has another effect which you should be aware of. It is part of
   the storage management algorithm. FR will not read an input module (of
   unknown length) unless it has enough free storage (string) space to
   hold a module of length MORE + 25 lines. This insures that any module
   can be loaded completely and FR will not run out of string space in the
   middle of loading a module. The larger you make "MORE", the more space
   is required. To get this space FR will delete modules. As the MORE
   limit is increased, at some point it will be so large that there
   will not be enough string space available to load even one module.
   If this occurs, FR will let you know.

   At the other end of the spectrum, if you set more=23, any file will be
   cut into page-sized chunks. You will never have space problems, and you
   can see all of every page without having to scroll any module. Then you
   can page thru the file with just the right and left arrow keys.

.MUSIC=Y/N     Enable the musical tunes at Sign-On and Sign-Off

   You may like these little tunes, or you may want to turn them off.

.NODES         Number of nodes allocated for the Node Pool

   This parameter is effective only during initialization. FR acquires
   its node pool dynamically, but once acquired and initialized, there
   is no provision for changing the pool size. This is because it is
   much easier just to re-start the program with a different value for
   "NODES", and also it is not something which you are likely to have
   to do very often.

   The initial value for NODES (1400) should work well with most data.
   If you work with data containing a lot of short lines, such as
   program source code, then you might want to increase this a little.
   Check the resource utilization from time to time using the "R"
   command. If you find that you are running out of nodes before
   lines, then you should increase NODES, and vice versa.

.PREFIX=xxx    Quote prefix used by EDITOR

   When you (E)dit a module, the module is copied to the editing work
   file with an optional quotation prefix defined by the PREFIX
   parameter. This is a convenience for replying to messages, so that
   you may include citations from the original message and these will
   be clearly distinguishable from your replies to them. For such work
   you can specify a character or short string to be used, such as
   "> ". For non-message work you would likely want to set the prefix
   to null.

.SC=Y/N        Show Count     (Optional Header Line Prefix)

   When the SC flag is Yes, the line count of each module is displayed in
   the Selection List as a prefix to each entry. This is useful when the
   modules are of widely varying sizes and you want to know how big each is.

   This prefix affects only the Reader Selection List display. It does not
   affect the text display, and it does not affect the format of any modules
   which are saved to another file.

.SM=Y/N        Show Mark      (Optional Header Line Prefix)

   When the SM flag is Yes, the Header Identification Mark is displayed in
   the selection list as a prefix to the module Headers, otherwise it is
   removed. This also affects the TEXT display, but not the input file
   itself, which is never changed by FR unless you open it for output.
   Also, when modules are copied, they are always identical to the input
   modules, regardless of any display editing done within FR.

.UM            Use Marks

   If UM=Yes, a module MARK and optionally an ENDMARK will be used to
   identify and load modules. If UM=NO, then the input file is loaded
   in modules of the size determined by the "MORE" parameter. Normally,
   if marks exist, you would want to use them. In some cases however
   part of a file may not be structured. For example, consider the source
   code for a program. If it has many subroutines, the subroutine headers
   can easily serve as marks which will make a separate module out of
   every subroutine. To see the main program and data areas, you can
   turn UM off and view the entire program in pages.