TEXT FILE VIEWER, BY DILWYN JONES APRIL 1995 (V1.15)
----------------------------------------------------

N.B. If using this program for the first time, use the up and down cursor arrow
keys to scroll through these instructions. To print them out, press P for Print,
enter the printer device name below when asked (e.g. SER1, or PAR) and WAIT!
Alternatively, you could use the COPY_N command from BASIC to send the file to
the printer, e.g.:     COPY_N FLP1_VIEWER_TXT TO SER1
If the cursor is not flashing, you cannot use the program. Type CTRL C (hold
down CTRL and tap the C key to make it flash) until it flashes.

Details of changes made in this and previous versions are now held at the end
of this text file.

This utility may be run on an expanded memory QL. It is a very simple to use
viewer for plain text files, similar in principle to those little viewer
programs that come with text-based shareware packages on the PC. I wrote it to
help with the distribution of converted information files into public domain.
It also permits the display of small embedded graphics in pointer environment
area save bitmap format. The file format for these pictures is:
          word      $4AFC  (identifier, decimal 74,252)
          word      width of picture in pixels
          word      height of picture in lines
          word      bytes per line across picture
          byte      screen mode (8=mode 8, 0 or 4 = mode 4)
          byte      spare
          followed by graphics image data as per screen layout

The QL already has some shareware and public domain editors such as QED which
can be used, but these are somewhat overkill for this application, where text
editing facilities or complex command line facilities are not required.

This viewer has two modes of operation, a "simple" mode where fewer commands are
available, making it more suitable for less experienced users and possibly more
suited to the needs of PD libraries who wish to supply this viewer with their
text files, and a mode where more commands such as sorting and block handling
may be implemented. This is one of the configurable choices.

This program does not allow you to edit text files; with the type of files I had
in mind which are basically information conveyors, that facility is best left
out. This program of mine is public domain and can be used to distribute such
text files or even applications such as text-only catalogues. The only
restriction I make on its distribution is that it should be freely given away
for no profit. You can make a small charge to cover your costs as per normal PD
distribution practice. Please include the program and this text file (the
instructions).

If you want to use this viewer to distribute COMMERCIAL software packages such
as data in the form of text files, please call to ask about terms. Normally
there will be no charge as long as the Viewer is incidental to the package as a
whole, though I may ask for a copy of the package in return!

This program was compiled using QLiberator and uses Norman Dunbar's DJToolkit
and Simon N. Goodwin's DIY Toolkit command EDLINE$. The configuration blocks
were prepared using Oliver Fink's BASCONFIG utility.

Facilities include:-
* Quick navigation through text files by use of cursor keys and Top/End commands
* Scroll bar indicator at right of screen for reference
* Simple one key commands
* Facility to chain in consecutive text files and return to calling file
* Filenames may be embedded in text to allow user to select files to load
* Allows simple menus to be constructed to select files to load
* Window may be moved and resized, from 12 to 54 lines (display permitting)
* Find and Next commands for quick and simple searches
* Merge facility to join several text files if you have expanded memory
* Save command allows merged files to be saved to disk
* Configurable with standard QJump Config program
* Order command allows viewer to be used for sorting simple lists
* Designed to be very simple to use, configurable for two levels of simplicity
* Pass filename to program to load at startup, e.g. these instructions!
* Configurable startup filename, e.g. for instructions or logo (PIC file)
* Built in help screen
* Facility to display graphics via embedded filenames
* Configurable display colour scheme
* Many configurable startup options!
* Optional IBM character set for display of untranslated PC text files.
* Facility to suppress display of end of line carriage return characters.
* Command line parameter startup options
* Fast Word Find via simple one key press (F5)


STARTING THE PROGRAM
--------------------

Simply execute it with the EXEC or EXEC_W command:-
EXEC FLP1_VIEWER_OBJ    (if you have QLiberator compiler runtimes installed)
or
EXEC FLP1_VIEWER_RTM    (if not! This version is about 10kilobytes longer and
                         includes the compiler runtimes)

Please note: If this viewer was supplied as part of a package from a software
supplier, e.g. for distributing information text files or catalogues, you
may only get one version of the program (usually VIEWER_RTM).

If you are unsure what the term 'QLiberator compiler runtimes' means, you will
normally use the version which has the filename ending with '_RTM'. If you
wish to use this viewer as part of a package of text files to be supplied to
someone else (e.g. PD libraries) and do not wish to supply both versions if they
take up too much room on the disk, you should supply VIEWER_RTM. The other
version will not work on systems which do not have the QLiberator compiler
runtimes on board.

If you want to make it load a text file automatically as it starts, you will
need to have Toolkit 2 active and use the EX or EW commands to allow a filename
of a text file to be passed as a parameter in those commands:-

EX FLP1_VIEWER_RTM;'FLP1_VIEWER_TXT'

It is also possible to make the program display a picture (e.g. a company logo
or picture based on the theme of the files to be shown). This facility can
also be used to load a text file if Toolkit 2 is not available. See below.


THE DISPLAY
-----------

NB - The instructions refer to particular colours for sections of the screen.
This is how I supply the program, where the top and bottom strips are red, with
the main text window in the middle black. Do bear in mind that colour schemes
are configurable, so you may receive a copy from someone else set to use
different colours!

The display of the program is divided into three sections, the red bit at the
top shows the commands available, the slightly taller red bit at the bottom
shows status and allows filenames etc to be entered, while the large black area
in the centre is used to show the text. Once a file has been loaded, a green
vertical scroll bar at the right hand side shows where you are in the file.
As you move through the file, the green bar changes position to reflect
your position in the file. If the green bar is at the top of the screen, you
are at the top of the text file. If the green bar is at the bottom of the
black area, you are at or near the end of the file. The longer the text file,
the shorter the green bar gets and the slower it will move. Remember that
the colour of the green scroll bar can be configured - I supply the
program with it configured to green normally.

It is possible to change the height of the display to show more or less lines on
the screen at a time. This is especially useful if you have a large screen
display such as on a QXL. Press CTRL F3 (hold down the CTRL key, tap the F3 key,
and finally let go of the CTRL key) and the program will change the size of its
display. On a standard QL, only 2 heights are possible. The smaller one occupies
about half the height of the standard QL screen and is useful if you wish to be
able to see the display of another program at the same time (e.g. the basic
command line), or if you have two copies of the viewer running and wish to
compare two text files for reference.

On a large screen, the program's display can also be moved around the display to
your preferred position. Press CTRL F4 and the program's display changes to just
the border. Using the cursor arrow keys you can slide this around the screen to
where you want it. This is not of much practical use on the standard QL screen
unless you are using the small size viewer display, but may prove useful on
larger display screens.

You may have noticed when trying to view or display text files converted from
a PC that the characters shown are not necessarily the same when displayed on
a QL. This is especially true where the file uses shading, box and line
graphics characters, which have no equivalent in the QL character set. The
Viewer has a built in IBM character set which can be used to display such
files a little more accurately. Press the F2 key to toggle between QDOS and
IBM character sets for the display. Please bear in mind that the IBM
character set needs a little over 2 kilobytes of free memory to work in. This
should not be a major restriction. Which font is used when the program starts up
is determined by a configurable option. See below.

It is possible to specify that the program does not display the end of line
carriage returns on converted text files. This prevents unsightly 'chequerboard'
characters being displayed at the end of each line. This facility is set by a
configurable startup option - it cannot be toggled within the program, since it
is not a display facility as such. What it does is to remove end of line
carriage returns as files are loaded and internally stores them without the
carriage returns. This provides a useful extra facility. If, with carriage
return suppression configured to be on, you load a text file, then save it again
under a different name, the saved file will not contain end of line carriage
returns, thus the viewer program is actually capable of removing these
characters from converted text files.


THE COMMANDS MENU
-----------------

The red line at the top of the screen shows the commands available:-
Block Chain End Find Merge Next Order Print Read Save Window

The first letter of each word is underlined and in upper case. Press this letter
key to activate that command. For example, press L to Load a file.

BLOCK - Allows you to extract a block of text which can be printed or saved to a
        separate text file. Examples of the use of this command might be to
        extract a verse or two from a religious text file, to extract a quote,
        or to extract single jokes from a text file containing several jokes.
        Only whole lines can be saved. The block starts at the current cursor
        line, so position the flashing red cursor on the line where the text
        extract starts, press B for Block to mark the end line (which may be
        above the first line marked if required) and finally enter a filename
        for the block extracted. If you specify a filename such as SER1 or PAR
        it is possible to print the block marked. Press ESC before marking the
        end point, or enter a blank filename to abandon the Block command.

CHAIN - If the current text file has a special filename marker at its end, this
        command will load that text file. This allows you to set up a series of
        text files to be loaded one after the other. Using any text editor, at
        the end of the first file place a filename enclosed by >>$$ and $$<<
        symbols, e.g. >>$$FLP1_NEXT_FILE_TXT$$<<
        Alternatively, the first text file could be a 'menu' file containing
        filenames of various available files, each of which would end with the
        filename of the 'menu' text file, thus providing an easy means to
        return to a menu via the Chain command after reading individual files.
        It must be on the last line of the file.This command is not shown
        while viewing in the editor. It is possible to use Chain to allow long
        files to be viewed on a small memory machine. Split up the text file,
        using your favourite text editor, or the Block command in this viewer
        for example, then edit each section to include the filename of the next
        section, so that the first file chains the second part, and so on.
        If you do not understand this facility, ignore it. You will not need to
        use it very often.

END   - Moves the cursor to the last line of text.

FIND  - Searches for a given text string, up to 80 characters long. Specify
        whether the search is to start from the Top or Current position, by
        pressing the T or C keys. The, enter a string to be searched for. The
        cursor will jump to a line which contains that text. The text may not
        straddle across the end of one line and the start of the next.

LOAD  - asks you to enter a filename of a plain text file to be loaded.Type this
        filename in and press ENTER. Individual lines should not exceed 80
        characters in length. Very long lines, or files which contain no
        linefeeds, may cause an error which makes the program stop.

MERGE - Allows you to join an extra text file onto the one currently loaded.
        This is useful if short text files are supplied for unexpanded machines
        but you wish to join them together as you have expanded memory. Enter
        the flename of the file to be merged.

NEXT  - Repeats the search for the last search text entered, starting from the
        current line (the line at which the cursor is currently located)

ORDER - Sorts the lines into alphabetical order, useful for quickly sorting a
        simple list of entries, e.g. for a sorted list of files on a disk, use
        the toolkit 2 command
        WDIR \RAM1_TEMP,FLP1_
        then load RAM1_TEMP into the viewer program and save it after sorting,
        or use the print command after using ORDER to sort it.

PRINT - Used to print the current file onto paper. Set up your printer ready and
        tell this program which printer device you'd like to print to (e.g. SER1
        or PAR for parallel printer ports such as the one on the Super Gold
        Card). Print and Save are largely interchangeable.

READ  - This option lets you load a text file or display a picture whose
        filename is indicated by the >>$$...$$<< markers on a line
        anywhere except the last line of the file (i.e. it must be visible).
        The '...' represents the filename of a _PIC file, that is,
        a pointer environment area save bitmap graphics file, whose file
        format is described above - these usually have the filename ending
        "_pic". Such graphics can be created using my Image Processor program
        (V2.09 or later), QDesign, The Clipart Utility, and they can
        also be cut out from larger screen files using a companion public
        domain program of mine, "PICer", available from QL PD libraries.
        Position the cursor on the line containing the name of the graphic,
        and press (R for Read) and the picture will be displayed. Press any
        key to return to the text. As graphics are fairly slow to display,
        it was felt that doing it this way, where you only occasionally need
        to refer to the pictures, was quite suitable. Remember that pictures
        taller than the current screen size cannot be displayed, so bear this
        in mind when preparing the graphics. If the file is not a _PIC file
        as identified by the preamble bytes in the file, it is loaded as
        a plain text file instead. By placing several filenames on
        consecutive lines, for example, you could create simple menus
        from which the user can select any of a number of files to load.
        Pressing SPACE or ENTER is equivalent to pressing R for Read.
        Note: don't attempt to load any graphics other than PIC files! The
              viewer only knows about PIC files, and will attempt to load
              other picture files such as screens as text, which may be
              rather disastrous!

SAVE  - asks you to enter a filename in order to save the current file. This
        command can't be used if no file has been loaded yet!

TOP   - Moves the cursor to the first line of the text.

WINDOW- Allows the display area to be moved around the screen. This can be
        helpful if using a large display (e.g. VGA or Graphics Card), since
        the viewer can be repositioned to reduce screen clutter.


CURSOR KEY COMMANDS
-------------------

You can use the up/down cursor arrow keys to move up and down through the text.
Using the SHIFT key with these keys (hold down SHIFT, tap the up or down key,
and finally release the SHIFT key) to move up and down by one screenful of text
at a time. To allow the PageUp and PageDown keys on add-on PC keyboards to be
used, ALT UP and ALT DOWN keys may also be used to move up and down a screenful
at a time. Subject to configuration, there may be a 1 or 2 line overlap between
screenfuls, or no overlap at all (see section on configuration). Use SHIFT ALT
and up/down keys jumps to the first or last line of the text - equivalent to the
TOP and END commands.

You can move the flashing red cursor right and left along a line if
this helps to maintain an eyeline on a column of text, or to follow an item in
an index along a largely blank line to a page number at the end of a line, for
example, though the horizontal cursor position has no direct effect on the
program operation.


OTHER COMMANDS
--------------

CTRL F3 toggles the size of the program's display, allowing more text to be
shown on larger displays such as QXL or Masterpiece. The smallest setting shows
just 12 lines of text, while the largest shows over 50 lines of text. The
display cycles through the possible sizes and back to the minimum size.

CTRL F4 - equivalent to the Window command, allows change of display position on
the screen. Use the cursor keys to steer the program around the screen, then
press ENTER to fix the position.

F1 - Help (also accessible by pressing H for Help). Shows the built in HELP
screen. If the display is less than 22 lines tall, you are asked to press a key
after the first screenful of text. ESC can be pressed to abandon it if required.

ESC - Quit from the program, though the program asks you to confirm that you
really want to quit first, with a Yes/No option. Note that this confirmation
request may be disabled from V1.15 via a configuration item.

CTRL ESC (or SHIFT ESC) - NB both keypresses made available in case of problems
with certain keyboard interfaces. This allows you to return to the previous
document if there was one. The program 'stacks' up to 9 document filenames as
you move from one to the other and lets you retrace your steps back through
them, useful for following a trail of embedded filenames, or if using a 'menu'
file which calls up various parts of a text package which all need to return to
the menu text file.

TAB - Searches forward for the next filename reference (i.e. searches for
occurrences of ">>$$". SHIFT TAB searches backward.

ENTER or SPACE - Equivalent to the Read command.

F4 or SHIFT F5 - redraws the display if corrupted for any reason (e.g. other
programs writing all over it. If using pointer environment, redrawing should
not be necessary.

F2 - toggle between IBM and QDOS character set (default is configurable).

F5 - Fast Word Find. If the cursor is positioned on text, the program scans back
and forward to determine the word to be searched for and scans for the next line
containing that text. Note that if the search word is contained in another
longer word, that will be found, e.g. ON will be found as part of ONE.


CONFIGURATION
-------------

The program has a QJump level 1 standard configuration block built in, meaning
you can use the Tony Tebby Config program (supplied with most pointer driven
software) to change the startup defaults, such as display size, default printer
device name and load/save drive names. It is also possible (from V1.04) to
specify a filename of a picture file (_PIC) file to load at startup. Be careful
that the dimensions of the _PIC file allow it to load in the configured
default text window display size. Actually, although this is intended to load
a startup logo, it can actually load a text file - it could be used to load
the instructions or an introductory text file, for example. From version 1.12,
you can also load a second picture or text file in this way. The intended use is
that one loads a PIC file, while the other loads a text file. From version 1.02,
(the version number is shown when you configure the program) you can also
configure the display colours - the ink and paper colours of the text display
area and the prompts area at the top and bottom of the screen, plus the border
colour and the colour of the scroll bar shown at the right of the screen.

Please note that the CONFIG program is not supplied, though as it is supplied
with many commercial programs, you will probably have a copy already. Either the
CONFIG or MENUCONFIG programs can be used.

Using Config is quite easy - use the EXEC command to start it, enter the
filename of this program (FLP1_VIEWER_OBJ or FLP1_VIEWER_RTM, whichever
version you normally use) and follow the instructions given. Some options
will need you to type something in and press ENTER (e.g. drive names),
while some ask you to choose one of a range of options by pressing the
SPACE bar to toggle between each of the available options (e.g. the height
of the window used to display the text), while the others ask you to enter
colour numbers, which should be from 0 to 255), examples below:

0=black, 2=red, 4=green, 7=white
other useful stipple combinations for paper colours:
16=dark red and black, 32=dark green on black
80=red and black lines for the prompts window
96=green and black lines for the prompts window
255=black and white stipple (for borders)

Other colours can be found by experimenting in basic by setting the paper
colour for a window and clearing it:
REPeat loop:INPUT #0,'Colour?';col:PAPER col:CLS

The items you can configure are as follows (NB Some of these options were not
implemented in versions before 1.12:-
A. Program display height in lines, may be 12,22,30,44,54 or 72 lines.Toggle by
   pressing SPACE or use keys 1 to 6 to select the one you want. Press ENTER to
   select the one shown and move on to the next.

B. Default printer device. Normally SER1 or SER2 (or PAR for a parallel port)

C. Default drive for loading text files. Normally FLP1_. A subdirectory may also
   be specified if required.

D. Default drive for saving text files. Normally FLP1_

E. Filename of picture (_PIC) file to be loaded at startup. This can be used to
   display a company logo or introductory picture. It has to be a pointer
   environment area save bitmap (uncompressed) such as those created with my PICer
   utility, later versions of Image Processor, QDesign and so on. If a file
   specified is not recognised as a PIC file, it is loaded as a text file.

F. Filename of a second _PIC or _TXT (picture or text file as E. above.

G. Display colours - 6 elements of the display colour may be set. Item F is the
   paper colour used for the text area. Enter a colour number from 0 to 255 (as
   used for the PAPER and INK commands in superbasic). I use '0' (black)

H. Ink colour for the text display area. I use '7' (white)

I. Paper colour for the prompts area at the top and bottom of the screen. I use
   '2' (red)

J. Ink colour for the prompts area. I use '7' (white)

K. Border colour. I use '255' (black and white)

L. Scroll bar colour (the little bar along the right of the screen which shows
   where you are in the text). I normally use '4' (green)

M. Lines of text overlap on using the PageUp/PageDown keypresses (SHIFT up/down)
   This may be none, 1 line, or two lines.

N. Hide embedded filename delimiters. If the '>> $$' etc markers in the text
   annoy you, or you simply wish to have the filenames highlighted in reverse
   video, set this to hide the markers. Two disadvantages to setting it are
   (i)  the program display output is slightly slower, and
   (ii) any >>$$ which may occur in the text which is not intended to mark
        a filename (unlikely!) will be hidden.

O. Simplified command prompts. The less used commands such as BLOCK, ORDER,
   MERGE and WINDOW are not shown, and are not available.This makes the program
   display less cluttered, and the program a bit less complex to use. Moving the
   window via CTRL F4 is still possible, though. PD libraries, for example, may
   use this facility to simplify the program when included with distributed text
   files.

P. Start up with QL font or IBM font. The IBM font is for use with text files
   converted from the PC, or certain bulletin board text files. Where these
   files include box, line and shading characters, it can be a bit difficult to
   display them on a QL, as the QL character set does not include these
   characters, so if you were supplying untranslated PC text files, for example,
   you could configure the program to start up with IBM character set instead.
   It is still possible to use the F2 key to toggle between the QL and PC
   character sets.

Q. Suppress carriage returns. This prevents the end of line carriage returns in
   text files transferred from other computers from being shown on the screen,
   but carriage returns anywhere else in the line may still be shown. This
   facility works by stripping the carriage returns (ASCII code 13) as the file
   is loaded. If the file is subsequently saved, it will be saved without the
   carriage returns. Setting this item to remove carriage returns has the side
   effect of making file loading times slightly longer.

R. Start x co-ordinate across for top left corner of the viewer display. For
   mode 4, this is the number of pixels across.

S. Start y co-ordinate down screen for top left corner of the viewer display,
   in pixel lines down.

T. Suppress the Yes/No query on pressing ESC to quit. Press the SPACE bar to
   toggle between the Yes and No options.


COMMAND LINE PARAMETERS
-----------------------

Barry Ansell asked me to add the facility to specify on an ad-hoc basis the
position for the top left corner of the display, so that the Viewer could be
started from within another program, in order to display Help text files, by
making the Viewer start at a given place on the screen to coincide with the
display of the other program. As well as being able to pass a filename parameter
in an EX or EW command, you can now add command switches after the filename.
These take the form of a space followed by a hyphen and a command letter
followed by one or two numeric parameters. Formally, this is:-
EX FLP1_VIEWER_RTM;'filename -Ln -Cx,y -Sz'

Any of the three commands may be used, but they must occur in the order given.

 -Ln  This command sets the line number at which the cursor will be placed in
the first loaded text file. The number 1 must be a valid line number within the
text file (i.e. it must not be greater than the number of lines of text in the
document). Remember that the first line is zero, so to make the cursor appear at
the 50th line of the text file, use the value 49. This command could be useful
in implementing context sensitive help files, for example, where a single text
file contains all the help text, and it can be loaded with the cursor at a given
help subject specified by line number.

 -Cx,y  This command sets the co-ordinate of the top left corner of the display
of the Viewer program. The format is two numeric parameters separated by a
comma. The first is the co-ordinate across (x) and the second the co-ordinate
down (y). If specified, this overrides any such value set in the configuration
process. Obviously, this facility is only really useful on the larger displays
found on QXL, QPC, Aurora etc.

 -Sz  This command sets the size of the Viewer display at startup. z is a value
from 1 to 6 as follows:
1=12 lines, 2=22 lines, 3=30 lines, 4=44 lines, 5=54 lines, 6=72 lines



EXAMPLE OF USE
--------------

Suppose we wanted to use this program to distribute a software catalogue on
disk and it is made up of 3 text files, plus an introductory company logo
and an introductory text file from which you can load one of the supplied
files and return to the introductory text from those files to choose the
next file to read. This would be the way in which you would use the viewer
for distribution of sets of text files.

A copy of the viewer can be configured to load the logo or picture as it starts
up (e.g. call it LOGO_pic) - it will be loaded and the user prompted to press
any key to continue.

You'd need a simple SuperBASIC boot program to load the viewer, and specify
a text file to load after the picture has been shown. You can either load your

Suppose our files have the names:
MENU_TXT
CATALOG1_TXT
CATALOG2_TXT
CATALOG3_TXT

The SuperBASIC boot program might be this simple:
100 TK2_EXT : REM FOR SYSTEMS WITH TOOLKIT 2 ONLY
110 EX FLP1_VIEWER_RTM;'FLP1_MENU_TXT'

First of all, create an opening text file (called MENU_TXT in this example)
with some text like this. It is helpful to offer the instructions text file
for this viewer too, as an option. Alternatively, the instructions could be
loaded first, and a Chain filename added to the end of the instructions, to
load your menu.

========================================
     FRED BLOGGS SOFTWARE CATALOGUE

Welcome to our software catalogue. Press
F1 for help on using the viewer program.
Place the cursor over the name of a file
you'd like to read and press 'R' to Read
in that file.To return here, use the 'C'
(Chain) command from within that file.
>>$$FLP1_VIEWER_TXT$$<<     Instructions
>>$$FLP1_CATALOG1_TXT$$<<   Software
>>$$FLP1_CATALOG2_TXT$$<<   Hardware
>>$$FLP1_CATALOG3_TXT$$<<   Books
========================================

For the main text files themselves,I suggest you start with a line of text such
as 'Press P to print this file, or C to return to list of files', or whatever
is suitable for the files you are distributing.

You could put a list of the filenames in each text file to allow the user to
call up any file required from within any file if you like.

After calling a text file from the 'menu' file, you can return to the menu file
by pressing CTRL ESC or SHIFT ESC. The viewer will normally go back to the first
file with the cursor on the line which it was on before the other file was
called up. This is useful where a list of files has to be read in order, as you
do not need to scroll down to the filenames list as you did in versions before
1.08 (facility added at request of SJPD).

If you want to be able to go round in circles, or go back to the first file,
ensure that the last text file contains the filename of the first file, the
last line of those files should be something like:
>>$$FLP1_MENU_TXT$$<<
This would allow you to use the Chain command to return to the menu text file.

Alternatively, include a line which explains that the user should press CTRL ESC
(or SHIFT ESC) to return to this first text file from within any others called
up, e.g. to return to MENU_TXT from CATALOG1_TXT, just press CTRL ESC.

Anyone using this viewer to distribute religious files, for example, could
include a line suggesting the use of the Block command to extract individual
sections from a file, allowing you to cut out individual passages as required.

If you wish to include graphics in such text files (e.g. software companies
may wish to include smaples of screens from their programs, or a company logo)
simply extract the graphic from the screen concerned (e.g. capture it with
Screen Snatcher from Quo Vadis Design) using the PICer program and place its
filename within markers on a line within the text:
>>$$FLP1_SAMPLE_PIC$$<<
Remember that the program can be configured to load a picture as it starts.

Remember also that the program automatically distinguishes between picture
(_PIC) files and plain text files - the same command (Read) is used for both.

Remember also that although the filename has to be at the start of a line,
there is no reason why you can't put other text to the right of the filename.
For example, this could be used to explain what each file is, as shown in the
example above.

Configure the program as required. I suggest you set it to simpler operation,
load a startup picture if required, load an initial text file, whether that be
this file of instructions or your introduction, and set filename delimiter
display to hidden so that filenames become highlighted to make life easier for
the users!

Experiment a little to see what is possible!


DEFAULT DRIVES
--------------

The 'default drive' configuration is only for the drive name offered when
entering filenames. The viewer will load files from the Toolkit 2 data default
drive (that set with the DATA_USE command in Superbasic). Please note, however,
that the program extracts a new default drive from the filename entered and does
this by taking the part of the filename up to the first '_' symbol. So if you
use the LOAD command and instead of entering FLP1_UPDATES_TXT, you enter just
UPDATES_TXT, it may well find and load the file, but the new default drive will
become 'UPDATES_'. It is not a good idea to do this when using the LOAD and
MERGE commands, but this can be useful for embedded filenames, where the drive
name need not be included in the filenames for 2 reasons. It is quicker to type
them in, and it less work for the user to change them all when trying to
transfer a package to hard disk, for example. Set the DATA_USE default in a BOOT
program and the viewer will usually try to load files from there. This does
depend on Toolkit 2 being available, of course.


FINALLY...
----------

I hope this viewer comes in useful to someone! And thanks to Steve Johnson and
Ron Dunnett for suggestions for facilities added to from Version 1.03, and to
Bruce Nicholls for testing the program on QXL displays. Thanks to Barry Ansell
for suggesting new facilities implemented in V1.12.

If you need to contact me about the program, please make sure you know the
version number, the rom version of your QL etc (usual details). This will
often save a lot of time and fiddling about asking you about them.


                     Written on a wet weekend in May 1995.
                      (Graphics facility added June 1995)
              (Extensively modified September and December 1995)

                    Dilwyn Jones, 41 Bro Emrys, Tal-y-bont,
                    Bangor, Gwynedd, LL57 3YT,Great Britain

                        Telephone/Fax : [+44] (0)1248-354023

            Internet Email (workplace) to : Dilwyn.Jones@bbc.co.uk



RELEASE HISTORY FOR TEXT FILE VIEWER
------------------------------------

V1.00 April 1995. First release version

V1.01 Sept. 1995. Window move bug (error condition check inverted) fixed.
                  Help no longer refers to a command called 'Quit' as ESC is
                  now used instead, and shown in the lower prompt window.
                  Refusal to load image file if cursor on last visible line
                  and there was a CHAIN filename at the end of the file fixed.

V1.02 13/09/95    Configuration block now includes display colour
                  configuration at the request of Steve "SJPD" Johnson.
                  'Image' and 'Chain' commands now extended - pressing ENTER
                  while the cursor is on a line which contains a
                  >>$$filename$$<< line will now automatically identify a
                  PIC file and load as an image, or load as a text file.
                  'Image' command renamed to 'Read' to reflect this change.
                  Pressing ENTER on filename is same as 'Read' command now.
                  'Chain' functions as before to allow automatic chaining
                  of a sequence of files, or to allow return to a 'menu'
                  text file after each file loaded.
                  Help file updated.
                  Commands list in top prompts area in now alphabetical order.
                  TAB to next >>$$ marker now works better (and documented!)

V1.03 14/09/95    Second attempt to get resizing to work properly on SMSQ
                  on QXL without pointer environment.
                  Flicker in lower prompts display redrawing removed, on
                  some occasions the lower window was redrawn twice in quick
                  succession.
                  Less pause when quitting from program now.

V1.04 16/09/95    Two extra configuration items:-
                  (i)  now possible to specify 0, 1 or 2 line overlap for
                       Page Up/Page Down (SHIFT cursor up and down keys)
                       at the request of Ron Dunnett. There, Ron, dunnett
                       (done it... sorry, couldn't resist that!)
                  (ii) possible to configure a filename for a screen to
                       load at startup - e.g. a company logo
                  Page Up/Page Down keys on Falkenberg extension keyboard
                  interface (corresponding to ALT up and ALT down), now
                  work, coded as existing SHIFT up/down cursor arrow keys.
                  Home and End keys correspond to ALT left and ALT right
                  cursor arrow keys respectively.

V1.05 21/09/95    Changes implemented after further feedback from Ron Dunnett.
                  A) Two extra configuration items:-
                     i) The delimiter markers around embedded filenames can
                        now be hidden (i.e. the >>$$ markers need no longer
                        be unsightly and visible. Instead, the program can
                        be configured to make embedded filenames (other than
                        the last line CHAIN filename) visible in reversed
                        colours as a highlight (i.e. usually in black ink on
                        white paper with the supplied default colour scheme).
                        This makes it easier to spot the filenames - just move
                        the cursor onto the highlight and press ENTER.
                     ii)Simplified command prompts - some facilities in the
                        Viewer are not used very often (Block, Merge, Order
                        and Window) so you can configure the program not to
                        implement them. This makes no difference to the size
                        of the program (they were very compact routines)
                        but makes the program a lot easier for less
                        experienced users. PD libraries could supply this
                        program with text file based material, configured
                        for the Simpler command set only, and as users get
                        more experienced with the Viewer, they can reconfigure
                        it themselves to offer the extended commands. The
                        simplified command set means the Viewer is more in
                        keeping with the original design idea of a very basic,
                        very simple to use program for viewing text files.
                        Important facilities like printing, searching and
                        display of graphics still work in 'Simpler' mode.
                  B) Filenames menu. By pressing F3 it is now possible to bring
                     up a menu containing a list (maximum 100 items) of the
                     filenames embedded in the text. You can then move the
                     white bar over the list of filenames, press SPACE or
                     ENTER over the one you want, and it will be loaded. Or
                     press ESC to abandon and go back to the original text.
                  C) bug fix - if the text file you tried to load was not
                     found, the error message was given and the program then
                     carried on. But the original text was not redrawn. It was
                     still there and could be redrawn with F4, but the bug is
                     now fixed.
                  D) Attempt to implement Ron Dunnett's suggestion of a
                     facility whereby you could return to a previous file after
                     reading another file called up from the first. While this
                     does not make it a true Hypertext viewer, it does allow
                     people like Ron to implement an introductory text file as
                     a sort of menu, call up one subsidiary text file, and
                     then make the program return to the original menu text
                     file. The facility is implemented as a 'stack' of
                     filenames, maximum depth 10 files. Each time you LOAD a
                     text file, the filename is added to the list of files
                     and if the list exceeds 10, the first is lost. This means
                     you can go back up to 9 or 10 levels, which should be
                     enough for most purposes. Return to the previous file
                     with SHIFT ESC or CTRL ESC (as opposed to ESC which quits
                     completely from the program).

V1.06 24/9/95     Help file now reflects changes made in V1.05.

V1.07 15/11/95    A few minor bugs reported have now been fixed:
                  (a) Fixed a bug where the ink colour was not being correctly
                  set in the lower prompts window when entering the name of a
                  file to be loaded - the ink colour of the text window was
                  used in error.
                  (b) In Yes/No prompts, in some cases the response (Y or N) was
                  printed twice, once in the correct place, a second time in
                  an almost random position. Sometimes it would not be noticed
                  as it may randomly appear on top of similar text.
                  The "Already exists. Delete Y/N ?" overwrite prompts in
                  save, block and print commands have been made consistent now.
                  (c) After a CHAIN command, the program should have displayed
                  the name of the file just loaded. In fact, it displayed the
                  name of the file which will next be loaded by CHAIN in error.

V1.08 05/12/95    Corrected a problem reported by John Gregory concerning an
                  unwanted 'Overwrite Y/N?' prompt issued when printing to
                  SER1/SER2/PAR on Gold Card and Super Gold Card. The attempt
                  to sort this out in V1.07 actually made it worse! Error
                  detection now works in a different way to get around the
                  original problem by rewriting the routine in a different way.
                  Display tidied up after any printing errors (e.g. bad or
                  changed medium errors issued to main text window when
                  printing to file).
                  Now possible to use an IBM style display font to display
                  PC text files which have not been character translated. Press
                  F2 to toggle between normal and IBM character set.
                  If a text file ended with a character other than a linefeed
                  the program used to give an 'end of file' error. This is now
                  trapped,although loading has slowed down slightly as a result
                  of the improved error trapping.
                  UPDATES_TXT now added to main instructions text file to
                  reduce number of files to be supplied when used as viewer
                  for PD packages.

V1.09 24/12/95    Bug fix - menu of embedded filenames (F3) may be wrong after
                  a MERGE operation due to line counter being wrongly
                  incremented after the embedded filenames list is drawn up.
                  Bug fix - if configured with MenuConfig while the program was
                  configured to load a picture or text file (i.e. that entry was
                  not blank when reconfigured), the string length counter was
                  corrupted causing a random amount of garbage to be scrolled up
                  the screen. Odd length element now fixed.
                  At the request of SJPD the program now stores the cursor
                  co-ordinates for return with CTRL ESC. So now one file can
                  call another, then return with the cursor at the same point as
                  it was when you left it, useful for 'menu files'.
                  Two new configurable items. The program can now be configured
                  to start up using the IBM character set if required. Also, the
                  program can be configured not to show unsightly carriage
                  return characters at the end of a line (the second item was
                  also a suggestion from SJPD).
                  Bug fix - stacked filename corrupted on CTRL ESC after display
                  resizing. Same bug also caused quit error on SMSQ during Y/N
                  response after ESC to quit following use of CTRL F3.
V1.10 28/12/95    Version number now shown in Help screen - press F1 in the
                  program.
V1.11 5/9/97      Fix bug in Next routine, where moving the cursor down after a
                  Find could prevent Next working. Unreleased version.
                  Viewer no longer works on an unexpanded QL.
V1.12 19/9/97     Second attempt at fixing Next bug.
                  Command line facilities requested by Barry Ansell added.
                  Second picture/text file may now be specified in Configuration
                  Startup co-ordinates may now be configured.
                  Better error trapping for startup size and position to cope
                  better with the new command line parameters.
V1.13 26/9/97     Fast Word Find (F5) implemented.
                  Find, Next and F5 now move the cursor to the start of the text
                  found on a line, rather than just to the line containing the
                  text.
                  Fixed bug in CTRL F3 (resize) which prevented resizing to the
                  new 72 line Aurora 1024x768 display mode. Note that SVGA size
                  also works in the 1024x576 display mode on Aurora, more by
                  luck than intention.
V1.14 05/10/97    Custom version for Barry Ansell, with the confirm prompt
                  following an ESC to quit removed. For use when displaying help
                  text files. To be replaced by an additional configuration
                  block entry in future versions.
V1.15 07/11/97    Configuration option mentioned above added, to allow the Quit-
                  Yes or No query after pressing ESC to quit to be suppressed.
