autoread manual.doc -L1

autoread manual.doc -L1






AUTOREAD

A program to allow easy reading of large text files
on a computer

Author: David R Grigg

Version 1:
June 1990.



MANUAL






1: IMPORTANT NOTICE!


If you are reading this file on your computer in any other way
than using AUTOREAD itself, then you are losing out on the
value of AUTOREAD, and you will also not be able to try out the
software as you follow the examples given later in this
document.

To read this document using AUTOREAD, go back to DOS and type:
AUTOREAD MANUAL.DOC .



DISCLAIMER


While every effort has been made to free AUTOREAD from errors,
NO RESPONSIBILITY IS ACCEPTED for any damage that may be caused
to your computer, disks or data by the use of AUTOREAD. If this
makes you nervous, try AUTOREAD out on a floppy disk first.




2: Introduction


I wrote this program because I often find myself in the
situation of having a large text file on my computer's hard
disk which I am using because it has some kind of information
of value to me. Usually it is the manual for a shareware
program.

I adore shareware. I think the concept of trusting people to
pay a modest fee for software they genuinely find useful is
terrific. And I use a lot of shareware (and pay the
appropriate registration fees).

But the manuals for most shareware programs are distributed as
a text file unless you pay extra (and I generally don't). So I
end up with very useful manuals in a very NON-useful form: a
large text file on my hard disk.

Sure, I can print out the manual, but this can consume enormous
amounts of time, paper and printer ribbons (the QEDIT manual,
for example, is some 5500 lines long). And besides, I can
never find the manual when I want it. And even if I can,
finding the information I want can be very hard.

Aren't computers supposed to make life easier? Yet reading a
document on a computer screen is still extremely primitive.
Certainly you can use a useful utility like LIST, but this is
still missing something. It's hard to navigate around in a
large text file, to find the next chapter, or to locate key
words. Using the FIND utility in such programs is some help,
of course, but you have to type in the key word, and hope you
have spelt and punctuated it properly.

AUTOREAD is my attempt to fill this perceived gap. It works
very much like LIST, but it allows you to progressively
establish landmarks in the text and to go instantly to them.

AUTOREAD allows the creation of several kinds of 'landmarks':

* Chapter Stops

* Pre-defined Keywords

* Temporary Bookmarks

These are all available via pull-down menus for easiest
possible use.

What all this means is that you can very easily create a
comprehensive index to a particular text file, enabling you to
instantly find the section or information you are looking for.
It makes reading a text file on your computer as easy as
reading a hard copy, and in some respects easier.


3: Shareware Notice


AUTOREAD took a lot of effort to create. And I am still
working on improving it.

Please note that AUTOREAD is not, never has been, and never
will be free or public domain software. It is shareware.

The shareware concept is extremely simple. If you obtain a
copy of a shareware program, find it useful to you, and wish to
continue using it, you must send the requested shareware fee to
the program author.

Shareware relies entirely on trust. But it is a concept which
has allowed the creation and distribution of a large body of
excellent software at very low cost.

If you find AUTOREAD of use, please print out and fill in the
enclosed LICENSE.DOC document, and send it with the requested
$15 shareware fee to:

David R Grigg,
1556 Main Road,
Research,
Victoria 3095
Australia.

NOTE:

Most commercial software forbids you to make copies of it.
But because AUTOREAD is shareware software, you are positively ENCOURAGED
to share copies of AUTOREAD around, copy it for your friends,
upload it to bulletin boards, etc. The only stipulations are that
all those who use AUTOREAD for longer than a trial period of 14 days
must pay the required shareware fee, and that AUTOREAD must be
distributed with all the associated files, being:

AUTOREAD EXE
LICENSE DOC
MANUAL ARD
MANUAL DOC
MANUAL IDX
README BAT
STATS DOC
STATS EXE




4: Installing AUTOREAD


AUTOREAD is extremely easy to install.

The only file absolutely necessary to operating AUTOREAD is
AUTOREAD.EXE, which you should copy either into the same
directory as the documents you wish to use it on, or
(especially if you have a hard disk) into a directory which is
listed in your DOS PATH command (this is usually specified in
your AUTOEXEC.BAT file).

Many hard disk users have a directory called \TOOLS on their
hard disk. This is a good place for AUTOREAD.

To use AUTOREAD on a particular text file (as an example, say a
file called MANUAL.DOC), you would enter the following at the
DOS prompt:

AUTOREAD MANUAL.DOC

If you don't enter the file name, you will be prompted for it.


5: Files Created by AUTOREAD


AUTOREAD maintains two different files of its own for every
text file that you use it on.

If you used it on a document called MANUAL.DOC, for example,
AUTOREAD would create the following files:

MANUAL.IDX
MANUAL.ARD

Unless you have changed the textfile since you last read it,
the .IDX file will be created only the first time you use
AUTOREAD on the text file. The .ARD file, however, is
constantly read and rewritten.

The .IDX file is an index of the starting points of each line
of the text file, and enables AUTOREAD to very speedily locate
parts of the file. If it offends you to have a lot of
additional files in a directory, you can delete this file, but
then AUTOREAD will need to recreate it each time you access the
text file that it indexes.

The .ARD file contains such data as the current location in the
file, a list of chapter stops and their starting lines, and a
list of keywords. Note that the .ARD file is an ordinary text
file, which means that you can use a text editor to manipulate
it directly.


NOTE:

If you just wish to use AUTOREAD quickly on a small file
you wish to look at but will probably never wish to fully
index and set up chapter stops on, you can append an
option, -Q, to the command line, eg:

AUTOREAD MANUAL.DOC -Q

This ensures that AUTOREAD will get rid of its .IDX file
on exit, and will not access or create an .ARD file.


6: The AUTOREAD screen


If you are using AUTOREAD to read this manual, you are already in the
default screen mode - Display Mode.

6.1 Display Mode


This is the DISPLAY mode of AUTOREAD. Note the top line, in
reverse colours, which indicates that you can press the
ESCAPE or ESC key to bring up the AUTOREAD Menu Bar, or hold
down the ALT key and then the press the X key on your
keyboard to exit AUTOREAD.

NOTE:

It is most important to exit AUTOREAD in the standard
way, by pressing Alt-X. Doing this saves important
information. If you exit in any other way (ie, by
simply turning off the computer, or by rebooting), this
information will not be saved.

At the bottom line of the screen you will see information on
the current line number, the current search direction, and
the pathname of the file being read.


6.2 Menu Mode


Pressing ESC changes the top line of the screen to a Menu
Bar. See the section on The AUTOREAD Menu Bar for further
information.



7: Moving Around in Your Document


The up and down arrow keys on your keyboard will scroll the
text on your screen in the indicated direction.

Pressing PAGE UP on your keyboard will move to the previous
screen-full of information. (Unless you are at the start of the
file, of course).

Pressing PAGE DOWN on your keyboard will move to the following
screen-full of information. (Unless you are at the end of the
file, of course).

Holding down the Control (CTRL) key on your keyboard and
pressing HOME will go to the start of the file.

Holding down the Control (CTRL) key on your keyboard and
pressing END will go to the end of the file.

It is also possible to move to specific areas of the file by
using the AUTOREAD menu bar (see next section).



8: The AUTOREAD Menu Bar


You can call up the AUTOREAD menu bar simply by pressing the
Escape (ESC) key on your keyboard.

The top line of your screen will alter to show a series of menu
choices, like this:

AUTOREAD: Go Chapter Keyword Mark Find Screen ???


The first entry will be highlighted. You can move
the highlight by pressing the left and right arrow keys on your
keyboard.

When the entry you want is highlighted, press the ENTER key on
your keyboard, and a sub-menu will appear.

Alternatively, you can simply press the first letter of your
menu choice, and the sub-menu will immediately appear. To
activate the Keywords sub-menu, for example, simply press the
'K' key on your keyboard.

What follows is a brief description of each of the sub-menus
and what they do. More detailed explanations are in following
chapters.


8.1 Go


The Go menu allows you to move quickly to different
positions in the file: the beginning, the middle, the end,
or to a specific line number.


8.2 Chapters


This is perhaps the most powerful part of AUTOREAD. This
menu allows you to find instantly any one of up to 200
'chapter stops', by selecting a description from a pull-down
menu. They are called 'chapter stops' because the idea is
that you can set up such stops at the beginning of chapters
or major sections in the document.

This menu allows you to find, create, delete or change an
existing chapter stop.

It also allows you to clear all existing chapter stops, or
to automatically make chapter stops at standard points in a
document.


8.3 Keywords


An AUTOREAD keyword is like a FIND command for pre-defined
strings. It means you can create a list of common or
especially important words, perhaps from the index of the
manual, and quickly point to them. Once you have chosen a
keyword to find, AUTOREAD will quickly scan the file looking
for the next occurrence of that keyword.

Note that you can alter the direction of the search from
this menu.

This menu allows you to find, create, or delete keywords.


8.4 Marks


'Marks' is short for 'bookmarks'. They work in a very
similar way to chapter stops, except that they are temporary
(they vanish when you exit AUTOREAD), and the listing
entries simply give the bookmark number and the line number,
rather than a description.

Bookmarks are intended as a quick way of placing a marker in
the text while you look for some other information, and then
being able to quickly return to where you left off.

Note also that when you exit AUTOREAD, the current position
in the file when you exited is stored, so that the next time
you use AUTOREAD to read the file, the screen will be the
same as when you exited the previous time.


8.5 Find


This menu lets you search for any text (not a pre-defined
keyword).

You can specify the direction of search from this menu.


8.6 Screen


This menu simply allows you to set the foreground colour and
background colour of the text on the screen.


8.7 ???


Choosing this option will bring up an information screen
about AUTOREAD. It is not a help screen (this may be built
into later versions of AUTOREAD).


9: Go Menu


The Go Menu looks like this:


Top ^Home
Middle -
End ^End
------------
Line Number


Move the highlight around with the up and down arrow keys.
When it is on the selection you want, press ENTER on the
keyboard. Alternatively, simply enter the first letter of your
choice.

You will note next to some of the entries their 'short forms',
eg for Top you will also see ^Home. This means that you can
enter the short form and have the action take place immediately
without needing to call up the AUTOREAD Menu Bar. In other
words, to go to the top (or start) of a file, you can either
press ESC to get the Menu Bar, then G for the Go Menu, then T
for top, or simply press down the Control Key on your keyboard
and then the HOME key.

This menu should be self-explanatory:


9.1 Top (^Home)


Goes to the start of the file.


9.2 Middle


Goes to the very middle line of the file.


9.3 Bottom (^End)


Goes to the end of the file.


9.4 Line Number


Lets you enter and go to a particular line number in the
file.


10: Chapters Menu


The Chapters Menu looks like this:


Find F2
Add
Change
Delete
----------
Clear
Make


As indicated earlier, 'Chapter Stops' are perhaps the most
powerful part of AUTOREAD. You can use it to move instantly to
the beginning of various chapters or sections within the text
file.

This menu allows you to find instantly any one of up to 200
'chapter stops', by selecting a description from a pull-down
menu.

The Chapters Menu also allows you to add, change and delete
such chapter stops, as described below:


10.1 Find (F2)


This brings up a menu of the existing chapter stops. You
can move the highlight to the wanted chapter stop by using
the up and down arrow keys. Note that if there are enough
chapter stops, the listing will scroll up and down within
the box. You can also use PAGE UP and PAGE DOWN to move
through the listing.

Once you have selected your desired chapter stop, press
ENTER, and the screen will immediately fill with the text
starting at the desired chapter stop.


10.2 Add Current


This allows you to set the current line (that is, the line
currently at the top of the display screen) as a chapter
stop. You will be prompted for a description.


10.3 Delete


This will allow you to get rid of a particular chapter stop,
which you identify from the same pull-down menu as for the
Find function.

You will be prompted to confirm the delete.


10.4 Change


This will allow you to edit the description of a particular
chapter stop, which you identify from the same pull-down
menu as for the Find function.

Note that in this version of AUTOREAD, Change does not allow
you to alter the line number of a chapter stop.


10.5 Clear


This allows you to get rid of ALL current chapter stops.
Please use this carefully!

You will be prompted to confirm the clear.



10.6 Make


This is an extremely powerful utility, and makes the job of
creating chapter stops in an existing document extremely
easy, particularly if the document author has used a
standard way of identifying chapter or section beginnings.

Make allows you to scan the whole document, looking for a
designated string of text, and setting a chapter stop once
it has found it. It is possible to set a line offset from
the searched for text, and a prefix for the description.

An example will make this easy to understand.


10.6.1 A Make Example

One of the first documents I used AUTOREAD on myself was
the manual for the excellent shareware text editor QEDIT.
This manual is some 5500 lines long.

The document author had used a line of equal signs '===='
to underline each chapter heading, and a graphic line
'' to underline each section heading.

I first made a pass with Make, searching for the line of
equal signs.

Once I selected Make, I was prompted for the text string
to search for. I entered four equal signs, =====.

I was then prompted for a line offset. This allows you
to specify a line OTHER than the one on which the text
string was found as the actual chapter stop. In my case,
since the wanted line was the line immediately ABOVE the
line of equal signs, I entered an offset of -1. (If I
had wanted the line of equal signs itself, I would have
entered 0).

I was then prompted for a prefix string. The real value
of this is for sections or sub-sections, so I simply
pressed ENTER instead of entering a prefix.

The program then took about 30 seconds to scan through
the whole QEDIT document and set up the chapter stops.
AUTOREAD took the first text on the line I indicated I
wanted the chapter stop on, and used this as its
description for that chapter stop.

I then wanted to set up sections as chapter stops, so I
carried out another pass with Make.

Once I selected Make, I was prompted for the text string
to search for. I entered four graphic line characters,
''. (I used the ALT key and the numeric keyboard to
enter these characters - refer you DOS manual if you
don't know how to do this).

I was then prompted for a line offset. As again the
wanted line was the one above the graphic line, I entered
an offset of -1.

I was then prompted for a prefix string. I now wanted to
use this feature, to distinguish the section headings
from the chapter headings in the Find Chapter pull-down
menu. So I entered a hyphen and a space, '- '. These
characters were placed before the description for all the
chapter stops created during this Make pass.

Another 30-40 seconds, and I had essentially the
equivalent of the contents page of the manual in the form
of a pull-down menu.

Here is part of the chapter stops menu I created for
QEDIT.DOC:


- COLORS
- TABLE OF CONTENTS
- ACKNOWLEDGEMENTS
- INTRODUCTION
- FEATURES
- SYSTEM REQUIREMENTS
- INSTALLATION
CHAPTER 1. USERS GUIDE FOR QEDIT
- QUICK START
- MENUS
- THE STATUS LINE
- FILES
- VIEWING AND GETTING AROUND IN THE TEX
- CURSOR MOVEMENT
- USING WINDOWS


10.7 Make is extremely useful if you are the author of a document
you want to use AUTOREAD with, and you need to make changes
to the document after you have already used AUTOREAD on it.
You can Clear the existing chapter stops, and use Make, to
very quickly re-establish those stops at new line numbers,
provided you have used some consistent means of identifying
chapters and sections.

This means need not be types of underline, as in the example
above, but could be the word CHAPTER in capitals (Note that
Make distinguishes between upper and lower case, unlike Find
Text and Find Keyword), or a special character or series of
characters (eg ---> ).

The best way to learn how Make works is to try it out.
Don't worry about making mistakes, you can always Clear and
start again.



11: Keywords Menu


A keyword is simply a text string to be found in your document,
and the Find Keyword function works exactly as does the Find
Text function, except that you don't need to type in the
required text: you simply select it from a pull-down menu.

The Index of a document is a great place to find useful
keywords.

The Keywords Menu looks like this:


Find F3
Add
Delete
--------
Search DOWN



11.1 Find (F3)


This brings up a menu of the existing keywords. You can
move the highlight to the wanted keyword by using the up and
down arrow keys. Note that if there are enough keywords,
the listing will scroll up and down within the box. You can
also use PAGE UP and PAGE DOWN to move through the listing.

Once you have selected your desired keyword, press ENTER,
and the screen will begin searching in the indicated
direction for the wanted keyword, putting up a display of
the current line number being searched. If the keyword
cannot be found, an error message will appear.

Note that unlike the Chapter Make command, Find Keyword
IGNORES the difference between upper and lower case. That
is, 'DOS', 'Dos' and 'dos' will all be found by the same
keyword choice.


11.2 Add


This prompts you for the text of a new keyword, which will
be added to the list of existing keywords in alphabetical
order.


11.3 Delete


This will allow you to get rid of a particular keyword,
which you identify from the same pull-down menu as for the
Find function.

You will be prompted to confirm the delete.


11.4 Search Direction


This specifies the current direction of search. The default
is DOWN, ie searches on increasing line numbers from the current
line.

UP searches to decreasing line numbers from the current line.

GLOBAL searches from beginning of file.

To toggle the direction, simply select this choice.


12: Marks Menu


Bookmarks are just like chapter stops - except that they are
volatile (they vanish when you exit AUTOREAD), and that they do
not have a description, just an ID number and a line number.

Bookmarks are intended as quick reference points to 'hold your
place' when you are looking for something else in a file. You
can only create a maximum of 10 bookmarks.

The Marks Menu looks like this:


Find F4
Add Current
Enter
Delete


12.1 Find (F4)


This brings up a menu of the existing bookmarks. You can
move the highlight to the wanted bookmark by using the up
and down arrow keys.

Once you have selected your desired bookmark, press ENTER,
and the screen will immediately fill with the text starting
at the desired bookmark.


12.2 Add Current


This allows you to set the current line (that is, the line
currently at the top of the display screen) as a bookmark.

You will be prompted for the bookmark number you wish this
line to be recorded against.


12.3 Enter



This allows you to enter a line number directly for a new
bookmark (ie, you don't have to have the display showing that
line as the current line).

You will be prompted for the bookmark number you wish this
line to be recorded against.


12.4 Delete


This will allow you to get rid of a particular bookmark,
which you identify from the same pull-down menu as for the
Find function.

You will be prompted to confirm the delete.



12.3 Function Key Setting & Finding Marks


Because bookmarks are mainly used for very rapid access to
temporary locations in the file, AUTOREAD allows you to
completely bypass the menu system in setting and finding
bookmarks.

While you are in DISPLAY mode and at a point in the text you
wish to return to after looking somewhere else, hold down the
SHIFT key and one of the function keys F1..F10. You will hear
a warbling sound, indicating that the equivalent bookmark has been
set at that point (ie, pressing Shift F2 sets bookmark 2).

After you have browsed elsewhere, you can hold down the ALT key
and the function key (F1...F10) corresponding to the bookmark you
set previously. You will immediately jump back to the place you
left.

Note that you can use ALT and the function keys to jump to ANY
bookmark, whether set with SHIFT + function key or set through
the Marks menu.



13: Find Menu


The Find Menu looks like this:


Find Text
Last Find:
---------------
Search DOWN



13.1 Find Text


This will prompt you for the text to be found.

Once you have entered your desired text, press ENTER, and
the screen will begin searching in the indicated direction
for the wanted text, putting up a display of the current
line number being searched. If the text cannot be found, an
error message will appear.

Note that unlike the Chapter Make command, Find Text IGNORES
the difference between upper and lower case. That is,
'DOS', 'Dos' and 'dos' will all be found by the same keyword
choice.


13.2 Last Find


This retains a memory of the last text string you looked
for, and enables you to select it again. Otherwise, it
works exactly like the Find Text command.


13.3 Search Direction


This specifies the current direction of search. The default
is DOWN, ie searches on increasing line numbers.

To toggle the direction, simply select this choice.


14: Screen Menu


This menu allows you to alter the foreground colour and
background colour of the displayed text for the duration of
your current session with AUTOREAD.

The Screen Menu looks like this:


Foreground WHITE
Background BLUE


Note that the current colours are shown on the menu.

Once you select the foreground or background colour, you will
be given a pull-down menu of the available colours.

Note that the colour change does not take effect until you have
pressed ESC to return to the display mode of AUTOREAD.


15: To Other Shareware Authors


It seems to me that AUTOREAD would be an extremely useful
program to distribute with your shareware manuals on disk.

However, it doesn't seem very fair to the users of your
software to be expected to pay a second shareware fee (to me)
for the use of AUTOREAD on your manual.

For this reason, I will provide a special version of AUTOREAD
which will be set up to read only your manual file or files,
from the same directory as those files. You will need to pay
me a shareware fee of $50 for this special version, and to
write to me with the names of the files you want it to be able
to read. I will then provide you with the special version. On
the other hand, your shareware users will need to pay no
additional fee to use AUTOREAD on your manual.

You will find it very easy to set up the customised version of
AUTOREAD to work with your manual, establishing chapter stops and
appropriate keywords, so that your users will find your on-disk
manual a truly easy-to-use and valuable reference.

However, if you do not want to set up the appropriate chapter
stops and keywords yourself, for an additional $25, if you supply
me with a copy of your manual, I will establish the appropriate
chapter stops and keywords and return the appropriate files to you.


16: Acknowledgements


AUTOREAD was written using Borland's Turbo Pascal 5.5, a great
compiler which goes on getting better and better, and making me
less and less keen to move to programming in C.

I used QEDIT Advanced 2.08 from SEMWARE as my text editor during
programming and for some of this manual. I've also mentioned
QEDIT in a number of places in this manual, to illustrate how
AUTOREAD can be used to make access to a large text file manual
easy, and I hope SEMWARE didn't mind me doing so!

QEDIT is the best text editor I have ever used, and spoils you
for all others. It is shareware, and I recommend you write to
SEMWARE at 730 Elk Cove Court, Kennesaw, Ga, USA for their
current prices.

Most of this manual was written using PC-Outline from Brown
Bag Software, also shareware, and a program I use intensively
for manuals, reports, etc, where section numbering and renumbering
is required. Write to Brown Bag Software, PO Box 60000, San
Francisco, CA 94160-1719, USA for current prices.


17: Version History


This is version 1.01 of AUTOREAD. There may well be a few bugs
in it. I would be grateful if those who find such bugs could
let me know. Similarly, if you have any ideas for ways of
improving the product, let me know.

17.1 Updates


1.01 : (2 July 1990)

- GLOBAL search direction added
- fix to bug allowing line 0 to be displayed in status
- fix to bug involving embedded '/' char in chapter
description


17.2 Planned Enhancements


In future, I plan to add the following features to AUTOREAD:

* Support for 43-line and 50-line screens

* Short-form function keys for most functions currently available
only from the menus.

* Auto-capture of keywords.

* Mouse operation.