home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
High Voltage Shareware
/
high1.zip
/
high1
/
DIR2
/
AUTOREAD.ZIP
/
MANUAL.DOC
< prev
next >
Wrap
Text File
|
1993-06-13
|
91KB
|
2,054 lines
╔═════════════════════════════════════════════════════════════════════╗
║ ┌──────────┐ ║
║ │ AUTOREAD │ ║
║ └──────────┘ ║
║ ║
║ A program to allow easy reading of large text files ║
║ on a computer ║
║ ║
║ MANUAL ║
║ ║
║ ║
║ Author: David R Grigg ║
║ A Product of Rightword Enterprises. ║
║ (C) Copyright David R Grigg 1991 ║
║ ║
║ ║
║ Version 2.00 ║
║ December 1992. ║
║ ║
║ ┌─────────────────────────────┐ ║
║ │ CONTACT DETAILS: │ ║
║ │ David R. Grigg, │ ║
║ │ 1556 Main Road, │ ║
║ │ Research, │ ║
║ │ Victoria 3095, │ ║
║ │ AUSTRALIA. │ ║
║ │ │ ║
║ │ Compuserve: [76264,2530] │ ║
║ └─────────────────────────────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════╝
Autoread Manual -i-
DISCLAIMER
──────────
While every effort has been made to free AUTOREAD from errors, and I
can't imagine how AUTOREAD could cause you any problems, as a matter
of prudent legality, please heed the following notice:
I, David R Grigg, accept NO RESPONSIBILITY OR LIABILITY 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. As
a matter of good practice you should always keep regular backups of
important files.
Autoread Manual -ii-
CONTENTS
────────
│ DISCLAIMER .................................................... i
│ 1: Introduction .............................................. 1
│ 2: Shareware Notice .......................................... 3
│ 3: Installing AUTOREAD ....................................... 4
│ 4: Files Created by AUTOREAD ................................. 5
│ 5: The AUTOREAD screen ....................................... 6
│ 5.1 Menus and Selecting Choices ............................ 6
│ 5.2 The File Open Dialog Box ............................... 6
│ 5.3 The Document Window .................................... 7
│ 5.4 Window Highlighting .................................... 7
│ 6. A Brief Tour of the AUTOREAD Menu Bar ...................... 9
│ 6.1 The = Menu ............................................. 9
│ 6.2 The File Menu .......................................... 9
│ 6.3 The Document Menu ...................................... 9
│ 6.3 The Chapter Menu ....................................... 9
│ 6.4 The Keywords Menu ..................................... 10
│ 6.5 The Bookmarks Menu .................................... 10
│ 6.6 The Search Menu ....................................... 10
│ 6.7 The Utilities Menu .................................... 11
│ 7: Document Menu ............................................ 12
│ 7.1 View (Home) ........................................... 12
│ 7.2 Top(^Home) ............................................ 12
│ 7.3 Middle ................................................ 12
│ 7.4 Bottom (^End) ......................................... 12
│ 7.5 Line Number ........................................... 13
│ 7.6 Page Number ........................................... 13
│ 7.7 Odd Page Set .......................................... 13
│ 7.8 Even Page Set ......................................... 14
│ 7.9 Preferences ........................................... 14
│ 7.9.1 Chapter Sort Order ............................... 14
│ 7.9.2 Show Level Prefixes and Level Prefix Symbol ...... 15
│ 7.9.3 Offset Display ................................... 15
│ 7.9.4 Save Last Session ................................ 15
│ 7.9.5 Start at Last Session ............................ 15
│ 7.9.6. Save Bookmarks .................................. 15
│ 8: Chapters Menu ............................................ 16
│ 8.1 View (F2) ............................................. 16
│ 8.2 Find(Enter) ........................................... 16
│ 8.3 Add Current Line (Ins or Alt-A) ....................... 17
│ 8.4 Delete ................................................ 17
│ 8.5 Edit .................................................. 17
│ 8.6 Promote and Demote .................................... 17
│ 8.7 Clear ................................................. 17
│ 8.8 Make .................................................. 17
│ 8.9 Textual Make .......................................... 18
│ 8.9.1 A Textual Make Example ........................... 18
│ 8.10 Procedural Make ....................................... 19
│ 8.11 UpperCase Make ....................................... 20
│ 8.12 Centred Make ......................................... 20
│ 8.13 Problems with Make ................................... 20
│ 8.14 The Stand-Alone Make Utility ......................... 21
│ 8.14.1 C - Clear Chapters .............................. 21
│ 8.14.2 T - Textual Make ................................ 22
│ 8.14.3 N - Numeric Procedural Make ..................... 22
│ 8.14.4 A - Alphabetical Procedural Make ................ 22
│ 8.14.5 U - UpperCase Make .............................. 22
Autoread Manual -iii-
│ 8.14.6 Example Make File: .............................. 22
│ 8.14.8 An Important Note! .............................. 22
│ 9: Keywords Menu ............................................ 23
│ 9.1 View (F3) ............................................. 23
│ 9.2 Find (Enter) .......................................... 23
│ 9.3 Add (Ins) ............................................. 23
│ 9.4 Delete (Del) .......................................... 23
│ 9.5 Edit (Ctrl-F3) ........................................ 23
│ 10: Bookmarks Menu .......................................... 24
│ 10.1 View (F4) ............................................ 24
│ 10.2 Find (Enter) ......................................... 24
│ 10.3 Add (Ins) ............................................ 24
│ 10.4 Delete (Del) .......................................... 24
│ 10.5 Edit (Ctrl-F4) ........................................ 25
│ 10.6 Function Key Setting & Finding Marks ................. 25
│ 11: Find Menu ............................................... 26
│ 11.1 Find Text (F5) ....................................... 26
│ 11.2 Last Find (F6) ....................................... 26
│ 11.3 Find In Chapter (Ctrl-F5) ............................ 26
│ 11.4 Last Chapter Find (Ctrl-F6) .......................... 26
│ 12: Utilities Menu .......................................... 27
│ 12.1 Screen Mode .......................................... 27
│ 12.2 Directories .......................................... 27
│ 12.3 Output Text .......................................... 27
│ 12.3.1 Screen .......................................... 28
│ 12.3.2 Chapter ......................................... 28
│ 12.3.3 Lines ........................................... 28
│ 12.3.4 Page Break ...................................... 28
│ 13: The Read-Only Version ................................... 29
│ 14: Acknowledgements ........................................ 30
│ 15: Version History ......................................... 31
│ 15.1 Updates ............................................. 31
│ APPENDIX A: FUNCTION KEY SUMMARY ............................. 33
│ APPENDIX B: COMMAND-LINE OPTIONS ............................. 34
│ APPENDIX C: THE .ARD FILE FORMAT ............................. 35
│ APPENDIX D: LIMITATIONS OF AUTOREAD .......................... 37
│ APPENDIX E: MUSINGS ON THE WRITING OF MANUALS ................ 38
│ APPENDIX F: UPGRADING TO VERSION 2.0x ........................ 39
│ APPENDIX G: RAVE REVIEWS AND UNSOLICITED TESTIMONIALS! ....... 40
Autoread Manual -1-
1: 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
* Predefined Keywords
* Temporary Bookmarks
These are all available via separate windows 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.
Another extremely valuable use of AUTOREAD is for the creation of on-
line help facilities. Several companies have purchased site-license
agreements for AUTOREAD for just this purpose. The command-line Find
Text function means that you can start up AUTOREAD and instantly zip
to the particular topic you are interested in. A read-only version of
AUTOREAD, called READAUTO, is available so you can create such a help
Autoread Manual -2-
system but prevent your users from messing up your set-up.
Note that one of the very best features of this latest release of
AUTOREAD (in my view) is its ability to handle VERY large documents,
possibly up to 80MB in size, though indexing such a document might
take a while...
Autoread Manual -3-
2: 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 $30 shareware fee
to:
David R Grigg,
1556 Main Road,
Research,
Victoria 3095
Australia.
In return, you will receive the current version of AUTOREAD,
registered and free of the annoying opening shareware message, and
also free from several limitations on size of document, number of
chapters and keywords which are built into the shareware version (I've
got to make a living somehow!).
For those in the US: personal cheques are acceptable.
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
MANUAL.DOC
MANUAL.ARI
MANUAL.ARD
LICENSE.DOC
README.BAT
CHAPMAKE.EXE
Autoread Manual -4-
3: Installing AUTOREAD
═══════════════════════
AUTOREAD is extremely easy to install.
The only file absolutely necessary to operating AUTOREAD is
AUTOREAD.EXE, which you should place 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.
NOTE: if you are upgrading from version 1.10 or before, you may care to
install version 2.00 in a different directory from your current version,
until you have tried it out. There are a lot of changes in this version,
and some features omitted. On balance, I believe this version is much
better than the earlier versions, but it would be as well for you to keep
your old version of AUTOREAD until you have made sure you are happy with
the new version.
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, AUTOREAD will open up, and you can
use the File Open menu choice to select the file you want.
Alternatively, if you start up with a command line like this:.
AUTOREAD *.TXT
...AUTOREAD will start up by showing you the File Open dialog box,
showing all the files that fit the specification you gave on the
command line.
NOTE:
If you don't enter a file extension (e.g. the .DOC above), then
AUTOREAD will attempt to find a file with the name you have given it,
with either of the following extensions:
.DOC
.TXT
If it still can't find the file, it will give up with an error
message.
Autoread Manual -5-
4: Files Created by AUTOREAD
═════════════════════════════
AUTOREAD maintains at least two different files of its own for every
text file that you use it on, and in some circumstances three.
If you used it on a document called MANUAL.DOC, for example, AUTOREAD
would create the following files:
MANUAL.ARI
MANUAL.ARD
...and if you chose Save Last Session or Save Bookmarks in the
Preferences dialog box (see page 14), the following file:
MANUAL.ARB
Unless you have changed the text-file since you last read it, the .ARI
file will be created only the first time you use AUTOREAD on the text
file. The .ARD file, however, may be rewritten many times as you add
data or alter preferences.
The .ARI 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 your preferences for this
document, a list of chapter stops and their starting lines, a list of
keywords, and some other information. Note that the .ARD file is an
ordinary text file, which means that you can use a text editor to
manipulate it directly. (See APPENDIX C on page 35 for details).
Users of versions prior to version 2.00 may wish to note that there
have been some minor changes to the format of the .ARD file, most
importantly in the order in which information is stored in the file,
and in the addition of some new data sections.
The .ARB file, saved only if certain preferences are set for the
document, contains any bookmarks you have created, and/or the Last
Session line number; that is, the line of the document you were
viewing when you closed the document (which is stored as bookmark #0).
From version 2.00, you can dictate where (ie, in what file directory)
these various files are created. This means you can now use AUTOREAD
on a file which is located on a write-protected disk, even for example
on a CD-ROM, by having the writable files elsewhere. However, unless
you specifically tell AUTOREAD otherwise, it will look for these files
in the same directory as the source document.
Autoread Manual -6-
5: The AUTOREAD screen
═══════════════════════
5.1: Menus and Selecting Choices
──────────────────────────────────────────────────────────────────────
You may well be familiar with using programs with pull-down menus and
moveable windows, either under Microsoft Windows, or programs running
under DOS which use the same kind of interface, in which case you can
probably skip this section of the manual.
If you are not using AUTOREAD to read this manual, please start it up
now by typing:
AUTOREAD MANUAL
at the command-line.
Note the Menu Bar at the top line of the screen, and the Status Line
at the bottom. At any time, you can pull down a menu from any of the
choices on the Menu Bar, in any one of several ways:
* By clicking on the menu choice with the mouse, if you are using one;
* By holding down the Alt key and then pressing the first letter of
your desired choice;
* By pressing F10 to highlight the first choice on the menu bar,
and then using the arrow keys to move across choices, and Enter to
select one.
Once you have a menu open, you can select a choice either by:
* Clicking on the choice with the mouse;
* Using the arrow keys to select the item you want and then
pressing Enter;
* Pressing the key corresponding to the letter in the item which is
highlighted in red.
* Pressing the key shown to the right of the choice - this is
usually called the "hot key" for the action, and not all choices have
them. You can also often use the hot key when the menu is not opened
up.
You will note that many choices are "greyed out" until you open a
document. These represent choices which are invalid for the current
state of the program. Obviously, you cannot close a document until
you have opened one! Note also that the current version of AUTOREAD
only allows one document to be open at a time, and so once you have
opened a document, the Open choice on the file menu is greyed out.
5.2: The File Open Dialog Box
──────────────────────────────────────────────────────────────────────
When you chose Open from the File menu, a dialog box will appear.
(A dialog box is just an area on the screen that lets you make choices).
Press the TAB key a few times. You will notice that different parts
of the box get highlighted. While a section is highlighted, you can
either enter text, or make some kind of selection. Of course, using a
mouse, all you need to is click on the area which wish to use. Note
in particular the green, drop-shadowed "buttons". You can either
click on these, or TAB the highlight to them and then press Enter.
Autoread Manual -7-
With the Open File dialog, you can either enter the file name you want
directly in the text input field, or select the wanted file in the
scrolling file list. Then just press Enter, or click on the "Open"
button to open the nominated file.
5.3: The Document Window
─────────────────────────────────────────────────────────────────────
Once you have opened a file, you may see a message on the Status Line
showing that AUTOREAD is busy creating an index. When this process is
finished, you may see a couple of boxes appear very briefly before
disappearing and being replaced by the Document Window. Don't worry
about these boxes, which may vanish so fast they appear just to be
flashes on your screen - AUTOREAD is just creating windows for
chapters, keywords and bookmarks, and then hiding them to get them out
of your way.
There are several points to note about the Document Window. Firstly, the
close button at the top left of the window, a dot of colour with square
brackets around it. Clicking on this point will close the window (and for
the Document Window, this will also close the document and other windows).
Without a mouse, just press the ESC key to close a window.
Secondly, note the scroll bars at the right hand side and bottom of
the Document window. Clicking on the arrows will scroll the document
in the direction indicated. You can also click in the areas above and
below the position indicator, which will cause the document to scroll
up or down a screenfull at a time. (Note that in this version, you
can't use the mouse to move the position indicator yourself - this is
a feature which will be included in later versions). Without a mouse,
you can just use the arrow keys or Page Up and Page Down keys to
scroll the document.
If you have a mouse, you can also re-size and re-position the window
on the screen. This may be useful when you have the Chapter or other
windows also open.
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.
5.4 Window Highlighting
─────────────────────────────────────────────────────────────────────
AUTOREAD Version 2 works with several kinds of windows. The Document
Window, the Chapter Window, the Keyword Window, and the Bookmark
Window. All of these windows can be open (or visible) at the same
time, and each allows you to use the keyboard to scroll through their
contents, or take some action on the current item. So how does the
program know which window you want to scroll, or to action?
The answer is that keystrokes always go to the currently highlighted
window. You can tell which is highlighted by the bright colour of its
border. You will often need to change which window is highlighted in
Autoread Manual -8-
order to make use of it. You can highlight a visible window (or make
a hidden window visible and highlighted) in two different ways:
* By clicking on it with the mouse (if it is visible);
* By pressing the "hot key" associated with the "View" choice for
that window, eg pressing F2 will make the Chapter window visible and
highlighted, pressing Home will make the Document Window highlighted.
* By selecting "View" from the appropriate menu.
Autoread Manual -9-
6. A Brief Tour of the AUTOREAD Menu Bar
════════════════════════════════════════
This chapter just gives you a quick overview of the choices available.
Further details of each menu bar choice are given in subsequent
chapters.
6.1 The = Menu
─────────────────────────────────────────────────────────────────────
This is sometimes called the control menu. There are only two
choices, the first "About" calls up copyright information about
AUTOREAD. The second is "Help", which brings up a simple help screen.
(For more detailed help, I suggest closing your current document and
calling up the AUTOREAD on-line manual - AUTOREAD is its own best help
system!
6.2 The File Menu
─────────────────────────────────────────────────────────────────────
The File menu lets you open and close documents, and to exit the
program. Note that you can close a document either by selecting this
choice, or by clicking on the close button of the Document Window, or
by pressing ESC when the Document Window is highlighted.
You may be surprised that there are no "Save" options on this menu.
That is because you always use AUTOREAD on existing documents, and
because chapter and keyword information is automatically saved when
necessary as you close the document. Note, however, that this means
that if you have created a lot of new chapter stops you should close
the document down properly rather than just turning off the computer.
6.3 The Document Menu
─────────────────────────────────────────────────────────────────────
The choices on this menu are only active when you have opened a
document.
Note the first choice - View, with a "hot key" of Home. You will need
to select this, or to press Home, in order to highlight the Document
Window when another window such as the Chapter window is currently
highlighted.
The Document menu allows you to move quickly to different positions in
the file: the beginning, the middle, the end, or to a specific line
number, or to find a particular page number.
There is also a choice on this menu called "Preferences", which lets
you set certain preferences for how you want AUTOREAD to treat this
particular document.
6.3 The Chapter Menu
─────────────────────────────────────────────────────────────────────
This is perhaps the most powerful part of AUTOREAD. This menu allows
you to find instantly any one of potentially thousands of '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.
The number of chapter stops allowed in the shareware version of
Autoread Manual -10-
AUTOREAD is 400; however if you register, you will be allowed to set
as many chapter stops as you wish up to the limits of the memory on
your computer.
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.
6.4 The Keywords Menu
─────────────────────────────────────────────────────────────────────
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. The current version allows you to have up to 250 keywords.
Once you have chosen a keyword to find, AUTOREAD will quickly scan the
file looking for the next occurrence of that keyword.
This menu allows you to find, create, or delete keywords.
6.5 The Bookmarks Menu
─────────────────────────────────────────────────────────────────────
Bookmarks work in a very similar way to chapter stops, except that
they are normally temporary (they vanish when you exit AUTOREAD unless
you've chosen "Save Bookmarks" as part of the document preferences),
and the listing entries simply give the bookmark number and the first
text on the line marked.
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 if you've chosen "Save Last Session" in the document
preferences, when you exit AUTOREAD the current position in the file
when you exited is stored, and when you restart this position is
automatically set as Bookmark 0, and marked "LAST SESSION" . If
you've also chosen "Start At Last Session" in the preferences, the
document will automatically go to this position when opened.
6.6 The Search Menu
─────────────────────────────────────────────────────────────────────
This menu lets you search for any text (not a pre-defined keyword),
either in the body of the document, or in the Chapter descriptions.
This latter search is a very quick way to search for a major topic
which is covered by a chapter heading.
6.7 The Utilities Menu
─────────────────────────────────────────────────────────────────────
This menu has several choices which allow you to do various useful
things: send part of the document to a printer or another file;
Autoread Manual -11-
specify the location of files that AUTOREAD needs; or change the
screen mode (the number of lines on the screen).
Autoread Manual -12-
7: Document Menu
═════════════════
The Document Menu looks like this:
┌────────────────┐
│ View Home│
│ ---------------│
│ Top ^Home│
│ Middle -│
│ End ^End│
│ ---------------│
│ Line Number │
│ ---------------│
│ Page Number │
│ Odd Page Set │
│ Even Page Set │
│ ---------------│
│ Preferences │
└────────────────┘
The Document menu is primarily to give you several ways of moving
around in the document, and to set document preferences.
7.1 View (Home)
─────────────────────────────────────────────────────────────────────
You need to select this, or to press the Home key, to highlight the
Document Window, and to bring it to the front (on top of any other
windows you may have open). Only when the Document Window is
highlighted will the rest of the choices on this menu work.
The next four choices on the menu should be self-explanatory:
7.2 Top(^Home)
─────────────────────────────────────────────────────────────────────
Goes to the start of the file.
7.3 Middle
─────────────────────────────────────────────────────────────────────
Goes to the very middle line of the file.
7.4 Bottom (^End)
─────────────────────────────────────────────────────────────────────
Goes to the end of the file.
7.5 Line Number
─────────────────────────────────────────────────────────────────────
Lets you enter and go to a particular line number in the document.
7.6 Page Number
─────────────────────────────────────────────────────────────────────
This is a very valuable function, allowing you to search for
particular page numbers in the document. This is very useful if the
Autoread Manual -13-
document comes with a contents page and index page which shows these
page numbers.
Searching for a page number is not as easy as it might sound, however,
because simply looking for a number such as say 25 will locate many
erroneous instances of the number which are not page numbers, such as
in tables, prices, and so on.
So AUTOREAD requires that you set a 'template' for what the page
numbering looks like in the document. Fortunately, this is very easy
to do, and only needs to be done once. This process is described in
the following two sub-sections.
Once you have created the template for a particular document, you will
never need to do it again, as AUTOREAD writes the template(s) to the
.ARD file.
This may all sound complex. However, FINDING a page once the template
is set could not be easier. Simply choose Page Number from the
Document Menu, and then enter the desired page. Note that you can
enter such constructs as '2-25' with no problems.
AUTOREAD then does a text search for the desired page, checking
instances of the number against its template.
You will note that the dialog box asks you if you want to start
searching globally, that is, from the top of the document, or from
your current position. The latter will be quicker if you are
confident the wanted page is further down in the document.
NOTE:
Page find is far from perfect. Its success will depend on the
consistency of the way the manual author has set up page numbering.
7.7 Odd Page Set
─────────────────────────────────────────────────────────────────────
To set up the page numbering template for odd pages, position the
document so that a line containing an odd page number is the current
line (with the < arrow symbol at the very right hand of the screen -
if you have not set any screen offset in the document preferences,
this will be the top line of the screen). E.g., in the Telix manual,
I positioned a line like this as the current line:
Telix v3.12 5
When you choose Odd Page Set, you will be shown the current line
(shorn of any unnecessary spaces at beginning and end, and perhaps
broken over two lines to fit into the dialog box) and asked what the
embedded page number is - in the example given it was 5. With
numbering of the form 2-5, you should enter this whole construct, i.e.
2-5, not just 5. That's all there is to it.
You will see that in the dialog box there is also a check box marked
"At Bottom of Page", and an input line to enter the page size. You
will only need to use these if the document author has placed the page
numbering at the bottom of the page, rather than the top. If you
Autoread Manual -14-
check the box, AUTOREAD will automatically offset the display by the
page size you have given, so as to bring the top of the wanted page to
the top of the display. You may need to experiment with this a little
to get it right.
NOTE:
If you don't explicitly do an Even Page Set, AUTOREAD assumes that
even numbered pages are identical to odd numbered pages unless told
otherwise. The same applies if you just do an Even Page Set and not
an Odd Page Set. You only need to set both if the headers for even
and odd pages are different.
NOTE:
Avoid positioning on a page whose number is embedded in other text on
the line, e.g., in the example given above it would have caused
problems to position on page 3,1,2 or 12, as these numbers are all
embedded in the 'Telix v3.12' string.
7.8 Even Page Set
─────────────────────────────────────────────────────────────────────
This is identical to Odd Page Set, except you should position the
current line to an EVEN numbered page. You only need to do this if
the format for even pages is different from that for odd pages.
7.9 Preferences
─────────────────────────────────────────────────────────────────────
This is a very important choice, allowing you to set may different
choices which affect how AUTOREAD will behave with the current
document. The preferences are saved in the .ARD file.
The current preferences you can set are as follows:
7.9.1 Chapter Sort Order
─────────────────────────────────────────────────────────────────────
Normally, AUTOREAD displays chapters in "natural" order, that is, the
order in which they appear in the document (line order). However, you
can change this so that the chapters are listed in alphabetical order
of their descriptions. This can be very useful for some kinds of
application.
NOTE that changing the sort order does not affect the current chapter
window. To make the changed order take effect, you must close the
document and re-open it. (This is a change from versions prior
to 2.00, but it has the advantage that AUTOREAD will always use the
nominated order for this document). Note also that you will normally
want to set Show Level Prefixes off (next preference) if you want
alphabetical order.
7.9.2 Show Level Prefixes and Level Prefix Symbol
─────────────────────────────────────────────────────────────────────
From version 2.00, you can nominate a "level" for chapter stops (see
next section for more detail). This allows subsidiary headings to be
treated differently from major headings, by indenting with a nominated
symbol.
Autoread Manual -15-
Normally, Show Level Prefixes is on, but you can uncheck this box to
turn off this effect. You can also nominate the symbol(s) you want to
use to mark levels.
7.9.3 Offset Display
─────────────────────────────────────────────────────────────────────
In some applications, it is useful to have AUTOREAD display a few
lines before the line on which a chapter stop has been set (an example
would be in long listings of bulletin board messages, where the
"Subject" line is generally three or four lines below the top of the
message). By setting the offset to a value other than zero, you can
have AUTOREAD behave in this way. It is not, however, a good idea to
set this value to anything more than, say, half a screen, or AUTOREAD
may behave in unexpected ways.
7.9.4 Save Last Session
─────────────────────────────────────────────────────────────────────
If you check this box, AUTOREAD will automatically save the position
in the document where you were at when you closed the document. From
version 2.00, this information is saved in the .ARB file, as Bookmark
0, described as Last Session.
7.9.5 Start at Last Session
─────────────────────────────────────────────────────────────────────
If you check this box, AUTOREAD will automatically open the Document
Window at the Last Session (Bookmark 0) point. This allows you to
keep reading through a long document through several sessions. NOTE
that if you check this box but the Last Session has not previously
been saved, you will start at the top of the document, as usual.
7.9.6 Save Bookmarks
─────────────────────────────────────────────────────────────────────
I always intended Bookmarks to be simply a temporary version of
Chapter stops, but after numerous requests from users, Bookmarks are
now saved in the .ARB file if you choose this option.
Autoread Manual -16-
8: Chapters Menu
═════════════════
The Chapters Menu looks like this:
┌─────────────────┐
│ View F2 │
│ Find Enter │
│ Add Ins │
│ Delete Del │
│ Edit Ctrl-F2 │
│ Promote Grey + │
│ Demote Grey - │
│ -------------- │
│ 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 hundreds of '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:
8.1 View (F2)
─────────────────────────────────────────────────────────────────────
You will need to take this choice, or press the "hot key" to make the
Chapter Window visible and highlighted, and to make the following
choices work.
Note that the Chapter Window can be resized and repositioned anywhere
you like, and that it stays visible until you close it, or until you
select the Document Window (which comes to the front and may obscure
the Chapter Window. You can page up and down through the Chapter
Window the same way as you can with the Document Window. Note also
that the Chapter Window stays scrolled to the same spot where you left
it last.
8.2 Find(Enter)
─────────────────────────────────────────────────────────────────────
Once you have selected your desired chapter stop, press ENTER, or
double-click on it with the mouse, and the Document Window will
immediately scroll to the text starting at the desired chapter stop.
The Document Window will be selected so you can see the text of the
document. If you want to choose another chapter, press F2 again:
the Chapter Window will still be scrolled to the place you were at
before.
8.3 Add Current Line (Ins or Alt-A)
─────────────────────────────────────────────────────────────────────
This allows you to set the current line (that is, the line currently
at the top of the display screen) as a chapter stop. If you make this
choice from the Chapters menu, you will be prompted for a description.
Autoread Manual -17-
However if you use the Alt-A key when the Document Window is
highlighted, there are no prompts - the computer will make a warbling
sound to show that it has captured the current line.
Note that as part of the dialog box, you can set a "level" for the
current chapter stop. Higher level numbers indicate more and more
subsidiary chapters, which are indented to the right in the Chapter
Window, allowing you to naturally reflect the structure of the
document with its major headings and sub-headings. Future versions
of AUTOREAD may allow you to supress display of lower level headings.
8.4 Delete
─────────────────────────────────────────────────────────────────────
This will allow you to get rid of a particular chapter stop. You'll
probably use this a good deal after carrying out a Chapter Make
function.
8.5 Edit
─────────────────────────────────────────────────────────────────────
This will allow you to edit the description of a particular chapter
stop.
8.6 Promote & Demote
─────────────────────────────────────────────────────────────────────
These options allow you to easily change the level of a chapter stop.
Promote (the + key on the numeric keypad) reduces the level number by
one (lower levels meaning higher priority). Demote (the - key on the
numeric keypad) increases the level number and indents the chapter
description accordingly.
8.7 Clear
─────────────────────────────────────────────────────────────────────
This allows you to get rid of ALL current chapter stops. Please use
this carefully!
You will be prompted to confirm the clear.
8.8 Make
─────────────────────────────────────────────────────────────────────
This is an extremely powerful utility, which allows you to
automatically create chapter stops from various kinds of clue in the
text of the document.
If you choose Make, you are taken to a sub-menu, which looks like
this:
┌────────────┐
│ Textual │
│ Procedural │
│ UpperCase │
│ Centred │
└────────────┘
These options are each described in the following sections.
Note: you can run any form of Make repeatedly on a file to identify
different levels of sections. However, in this version of AUTOREAD,
the software will not let you add two identical chapter stops - the
second will just never be added. "Identical" depends on whether you
have the chapter sort order set to Line or Alpha. If it is Line, you
can't set two chapter stops which jump to the same line. If it is
Alpha, you can't set two chapter stops with identical descriptions.
For this reason, there is no need in this version for the "Remove"
option in earlier versions which eliminated such duplicates.
Autoread Manual -18-
8.9 Textual Make
─────────────────────────────────────────────────────────────────────
Textual make is the most secure form of the Make command, but will
only work for documents where the document author has used a standard
way of identifying chapter or section beginnings.
Textual 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 to specify which "level" the chapter stop should be at.
An example will make this easy to understand.
8.9.1 A Textual 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 Textual Make, searching for the line of equal
signs. Once I selected Textual Make, I was prompted for the text
string to search for. I entered four equal signs, =====.
I entered a line offset of 1, and specified that the chapter
description was ABOVE the found text, that is, immediately above the
underlining found. If I had wanted the line of equal signs itself to
be the chapter stop, I would have entered a line offset of 0.
I also specified that these chapter stops should have the highest
level of significance, and so set Level to 1.
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 Textual Make.
Once I selected Textual 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
to your DOS manual if you don't know how to do this).
Again the wanted line was the one above the graphic line, I entered an
offset of 1, and clicked on ABOVE.
This time I set the Level to 2, to make these chapters subsidiary
headings.
Autoread Manual -19-
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 │
└──────────────────────────────────────────┘
If you are using AUTOREAD on a document you are editing, then I
recommend the use of the stand-alone Make utility, described below.
Note that the means of designating chapter stops 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 (e.g. ---> ).
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.
8.10 Procedural Make
─────────────────────────────────────────────────────────────────────
I added this function after I had been using AUTOREAD myself on quite
a number of different shareware manuals. While the textual make
function works very well for manuals where the author has used some
standard form of underlining or text identifying the start of chapters
and sections, it proves awkward for instances where the author has
only used section numbering of the 'procedural' form, i.e.:
│ 1. INTRODUCTION
│ 1.1 Hello
│ 1.2 Goodbye
│ 1.2.1 Farewell
│ 1.2.2 Cheerio.
So I added this function. The dialog box for Procedural Make will let
you specify whether the section numbering is numeric or alphabetic
(some authors have appendixes sectioned off in the form:A.1, A.2, B.1,
etc). You can also specify what the separation character should be
(in most cases this will be a period, which is the default).
Once you have made these choices, the program takes over. If numeric
sectioning was chosen, then AUTOREAD will identify as a chapter stop
Autoread Manual -20-
any line whose first text was a number, and if that number was
followed by a period (or other separator you specified) before any
other character. It will also count the number of periods in the
section number, and set the Level for the description appropriately.
If alphabetic sectioning was chosen, then AUTOREAD will identify as a
chapter stop any line whose first character was an upper-case letter
and whose second character was a period (or specified separator).
8.11 UpperCase Make
─────────────────────────────────────────────────────────────────────
I added this form of Make when I discovered that there were manuals
(PKZIP is a good example) where the ONLY indication of a chapter or
section heading was that the heading was all in upper case (capitals).
UpperCase Make works by checking each line of the document to see if
it is all in upper-case. Because this is such an uncertain means of
identifying chapters, the dialog box allows you to set several other
conditions relating to whether non-alpha characters are allowed at the
beginning or ending of the line, and whether blanks preceding the text
are allowed or required (some authors centre their uppercase
headings). Note that if you specify than N blanks MUST be present,
this overrides a specification that LESS than N blanks are allowed.
Any line meeting all these requirements will be identified
as a chapter stop.
8.12 Centred Make
─────────────────────────────────────────────────────────────────────
This is a last gasp attempt to identify chapter headings! This type
of Make tries to identify headings which have been approximately
centred between left and right margins. It requires you to specify a
minimum number of blanks at left and right of the header, and the
approximate page width. It also asks for 'tolerance'. The bigger this
number, the greater the deviation from perfect centering is allowed.
8.13 Problems with Make
─────────────────────────────────────────────────────────────────────
Almost inevitably, with any of the above forms of Make, you will end
up with some invalid chapter stops. You can either use the Delete
function from the Chapter menu to remove these, or edit the .ARD
directly (see APPENDIX C on page 36).
One particular trap with Procedural Make is Contents Pages.
AUTOREAD naturally cannot tell the difference from a section heading
in the body of the text and that heading repeated in the Contents
Page. If you have a document with a problem contents page, simply
position the current line so it is after the contents page, and then
when you do the make, select "From Current Line" rather than "From
Beginning of Document" in the dialog box.
UpperCase Make is very subject to erroneous entries, because all it
has to go on is a line which is all in capitals. However, the
additional conditions you can now set in this version allow you to
eliminate some false hits, and it is now also much easier to delete
erroneous entries as you step through the document.
Centred Make is a 'last resort' choice, and you should use it only for
manuals where the only indication of a heading is a rough centering of
the heading text. Almost certainly you'll get lots of false hits.
8.14 The Stand-Alone Make Utility
─────────────────────────────────────────────────────────────────────
Particularly for the use of those using AUTOREAD as a help system, and
for shareware authors who might like to distribute a special version
of AUTOREAD with their shareware manuals (see page 30), I have
provided a stand-alone chapter make utility, CHAPMAKE.EXE. This is
also useful to anyone using AUTOREAD on a document which for whatever
reason has to be altered regularly.
Autoread Manual -21-
The advantage of this utility is that it allows you to set up an
automated chapter make which you can run each time you have made a
significant change to your manual or other document you wish to use
AUTOREAD on.
To run CHAPMAKE, enter a command line such as the following:
CHAPMAKE MANUAL
However, you must first create a text file with the make commands in
it. This file normally has the same name as the document you'll use
AUTOREAD on, but with an extent of .MAK. So if your document is called
MANUAL.DOC, then the make file will be called MANUAL.MAK. Note
however that you can optionally use a standard make file by including
its name on the command line, e.g.:
CHAPMAKE MANUAL STANDARD.MAK
This has the advantage of being able to use a single standard make
file for several different manuals.
The make file can have any number of command lines. The current
commands are described as follows:
8.14.1 C - Clear Chapters
─────────────────────────────────────────────────────────────────────
A line with the character 'C' at its start will clear all existing
chapter stops, just as if you had selected Clear from the Chapters
Menu.
Note that any existing keywords are left untouched.
8.14.2 T - Textual Make
─────────────────────────────────────────────────────────────────────
A line starting with 'T' has the effect of a Textual Make command as
selected from the Chapters Menu.
The 'M' must be followed by the text to search for, the line offset,
and the level, all separated by slashes (/). These are exactly as you
would enter them in the menu-driven make utility within AUTOREAD.
For example, take the following line:
T/***/-1/1
This line in the make file would set up as chapter stops the lines
preceding the text ''***", and would set the level to 1.
8.14.3 N - Numeric Procedural Make
─────────────────────────────────────────────────────────────────────
A line beginning with 'N' acts exactly as if you had chosen Procedural
Make from the Chapters Menu, and then selected Numeric section
numbering. You can follow the 'N' with a slash and a character to
indicate the separator if it is anything other than a period.
Autoread Manual -22-
8.14.4 A - Alphabetical Procedural Make
─────────────────────────────────────────────────────────────────────
A line beginning with 'A' acts exactly as if you had chosen Procedural
Make from the Chapters Menu, and then selected Alphabetic section
numbering.You can follow the 'A' with a slash and a character to
indicate the separator if it is anything other than a period.
8.14.5 U - UpperCase Make
─────────────────────────────────────────────────────────────────────
A line beginning with 'U' acts exactly as if you had chosen UpperCase
Make from the Chapters Menu.
8.14.6 Example Make File:
─────────────────────────────────────────────────────────────────────
This is the Make file I use for the AUTOREAD manual:
C
T/ ═════/-1/1
N
8.14.8 An Important Note!
─────────────────────────────────────────────────────────────────────
At present, CHAPMAKE is limited in how much you can control the make
process. This means that you can't specify a starting line for any
methods (CHAPMAKE will start searching at the beginning of the
document), nor can you specify conditions for the uppercase make type.
Autoread Manual -23-
9: 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:
┌──────────────────┐
│ View F3 │
│ Find Enter │
│ Add Ins │
│ Delete Del │
│ Edit Ctrl-F3 │
└──────────────────┘
9.1 View (F3)
─────────────────────────────────────────────────────────────────────
This brings up a scrolling window of the existing keywords. You can
move the highlight to the wanted keyword by using the up and down
arrow keys or the scroll bars.
9.2 Find (Enter)
─────────────────────────────────────────────────────────────────────
Once you have selected your desired keyword, press ENTER, and the
screen will begin searching from the current line for the wanted
keyword. 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.
Once the keyword is found, the first occurrence of the wanted keyword
will be on the top line of the Document Window, and all occurrences of
the keyword on the current screen will be highlighted in the current
highlight colour.
9.3 Add (Ins)
─────────────────────────────────────────────────────────────────────
This prompts you for the text of a new keyword, which will be added to
the list of existing keywords in alphabetical order.
9.4 Delete (Del)
─────────────────────────────────────────────────────────────────────
This will allow you to get rid of a particular keyword.
9.5 Edit (Ctrl-F3)
─────────────────────────────────────────────────────────────────────
This lets you change the highlighted keyword.
Autoread Manual -24-
10: Bookmarks 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:
┌─────────────────┐
│ View F4 │
│ Find Enter │
│ Add Ins │
│ Delete Del │
│ Edit Ctrl-F4 │
└─────────────────┘
10.1 View (F4)
─────────────────────────────────────────────────────────────────────
This brings up a scrolling window of the existing bookmarks. You can
move the highlight to the wanted bookmark by using the up and down
arrow keys or the scroll bars.
10.2 Find (Enter)
─────────────────────────────────────────────────────────────────────
Once you have selected your desired bookmark, press ENTER, and the
Document Window will immediately fill with the text starting at the
desired bookmark.
10.3 Add (Ins)
─────────────────────────────────────────────────────────────────────
This allows you to set the current line as a bookmark. Note that, as
with Chapter stops, you can alter the text of the description as you
wish (eg, you could change it to read "IMPORTANT BIT ON BOOKMARKS").
You will be prompted for the bookmark number you wish this line to be
recorded against. You can have up to 9 bookmarks at any one time.
10.4 Delete (Del)
─────────────────────────────────────────────────────────────────────
This clears the currently highlighted bookmark.
10.5 Edit (Ctrl-F4)
─────────────────────────────────────────────────────────────────────
This lets you alter the currently highlighted bookmark.
Autoread Manual -25-
10.6 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 the Document Window 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..F9. You will hear a warbling
sound, indicating that the equivalent bookmark has been set at that
point (i.e., pressing Shift F2 sets bookmark 2).
After you have browsed elsewhere, you can hold down the ALT key and
the function key (F1...F9) 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
Bookmarks menu.
NOTE: If you have selected Save Last Session in the document
preferences, AUTOREAD will automatically make bookmark 0 correspond to
the last position you were reading when you closed the document last
time. ALT-F10 will take you to this bookmark immediately, or you can
just select it from the Bookmarks Window.
Autoread Manual -26-
11: Find Menu
══════════════
The Find Menu looks like this:
┌────────────────────────────┐
│ Find Text F5 │
│ Last Find: F6 │
│ -------------------------- │
│ Find In Chapter: Ctrl-F5 │
│ Last Chapter Find: Ctrl-F6 │
└────────────────────────────┘
11.1 Find Text (F5)
─────────────────────────────────────────────────────────────────────
This will prompt you for the text to be found. You can specify
whether you wish the match to ignore upper and lower case
distinctions, and the direction of the search.
Once you have entered your desired text, press ENTER or click on the
OK button, and the screen will begin searching in the indicated
direction for the wanted text. If the text cannot be found, an error
message will appear.
Once the wanted text is found, the first occurrence of the wanted text
will be shown on the top line of the Document Window, and all
occurrences of the wanted text on the current screen will be
highlighted in the current highlight colour.
11.2 Last Find (F6)
─────────────────────────────────────────────────────────────────────
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.
Note that finding a keyword is treated as a find-text command, so that
Last Find can be used to repeatedly find the same keyword.
11.3 Find In Chapter (Ctrl-F5)
─────────────────────────────────────────────────────────────────────
This allows you to search for a text string in the Chapter Stop list.
This can be a very quick way to find a topic in a large document,
which has hundreds of chapter stops.
Find In Chapter searches ONLY the chapter stop descriptions. Otherwise,
it works exactly like find text.
11.4 Last Chapter Find (Ctrl-F6)
─────────────────────────────────────────────────────────────────────
This just searches again in the chapter descriptions from the current
point for the same text as your last chapter search.
Autoread Manual -27-
12.: Utilities Menu
════════════════════
The Utilities Menu looks like this:
┌─────────────┐
│ Screen Mode │
│ Directories │
│ Output Text │
└─────────────┘
12.1 Screen Mode
─────────────────────────────────────────────────────────────────────
This brings up a dialog box which lets you alter the number of lines
you can see on your screen (provided your video card and monitor
support this). Using AUTOREAD with more than 25 lines on the screen
is often the best (if you have good eyesight), because you can see
quite a bit of the document text while keeping the Chapter Window
visible and handy.
12.2 Directories
─────────────────────────────────────────────────────────────────────
The ONLY time you will need to use this option is if you have a
particular wish or need to place the AUTOREAD-created files in a
directory other than the one that the document you are reading is in.
Why might you need to do this? Well, the source document might be on
a write-protected disk, for example, and using the AUTOREAD defaults
would cause trouble, because the program wouldn't be able to create an
index file on that disk. A classic example would be a document on a
CD-ROM, which is by definition write-protected.
Or you might be on a network, where the source document and its index
are on a server, but you want to keep your own personal bookmarks file
in your personal directory.
Altering the default directories gives you a lot more flexibility.
Note, however, that you must alter the directories BEFORE you open the
source document. You can also do this on the command line (see page
35), allowing you to open a document on the command line with the
directories set as you wish them.
12.3 Output Text
─────────────────────────────────────────────────────────────────────
This choice allows you to copy ('dump') parts of the document you are
reading either to another file, or to the printer.
The choices shown in the dialog box for this choice relate to what
parts of the document you wish to be dumped, and whether you wish to
dump to a file or a printer. In the case of a file, you must enter a
file name. If the file already exists, you will be asked if you wish
to append to the end of the file, or to overwrite the existing file
(i.e., destroy it and start again).
The following describe the action of the various dump dialog box
options for the scope of the material to be dumped.
Autoread Manual -28-
12.3.1 Screen
─────────────────────────────────────────────────────────────────────
Choosing this will dump just what you can see on the display screen at
the current time, less the top and bottom status lines.
12.3.2 Chapter
─────────────────────────────────────────────────────────────────────
This will dump the entire current chapter or section. AUTOREAD will
determine the 'current chapter' as the material between the chapter
stop prior to the current line number, up to the line before the
chapter stop following the current line number. If you position a
chapter stop heading as the current line, then dump, you will dump
from that heading to just before the next chapter stop heading.
12.3.3 Lines
─────────────────────────────────────────────────────────────────────
This lets you enter your own start and ending line for the dump.
Entering '1' for the first line, and some number larger than the last
line in the file will dump the entire document.
12.3.4 Page Break
─────────────────────────────────────────────────────────────────────
This simply lets you send a form feed to the printer, or to embed a
form-feed character (^L) in the file.
Autoread Manual -29-
13: The Read-Only Version
══════════════════════════
For companies wishing to use AUTOREAD to set up on-line help systems,
shareware authors, and others wanting to distribute a version of
AUTOREAD with manuals, there is a special "read-only" version of
AUTOREAD (called READAUTO) which omits some features (such as Make),
which are of use only to users wanting to use AUTOREAD on any
document, and prevents users from making changes to your chapter stops
and keywords. Please contact me about a license fee which will allow
you to distribute as many copies of the special version with your own
manuals as you require.
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.
Autoread Manual -30-
14: Acknowledgements
═════════════════════
AUTOREAD was written using Borland's Turbo Pascal (Versions 5.5
and 6.0), a great compiler which goes on getting better and better,
especially with the Turbo Vision interface I have used in version 2.0.
I used QEDIT Advanced 2.08 from SEMWARE as my text editor during
programming and for early versions 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 still terrific, but SEMWARE have just developed an even better
editor called The Semware Editor (TSE), which is phenomenal! For these
products, I recommend you write to SEMWARE at Suite C3A,
4343 Shallowford Rd, Marietta, GA 30062-5022 USA for their current prices.
The printed version of this manual was produced with Microsoft Word
for Windows, on a Hewlett-Packard DeskJet 500, both terrific products.
Thanks to Don Avila, Russell Herman, Jerrold Maxwell, Terry Allen,
Rick Foster, Ralph Bednarski and many others for reporting bugs and
suggesting improvements to AUTOREAD.
Autoread Manual -31-
15: Version History
════════════════════
This is version 2.00 of AUTOREAD, and it is a total re-write from
versions 1.00 thru 1.10. There may still 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,
please let me know. In particular, there are some features of
AUTOREAD version 1.10 that I have had to leave out of version 2.00
because of the different way things are handled under the Turbo Vision
interface (and to prevent the program size blowing out even more!). I
really need to know how important these missing features are to you.
If they are vital, I will make every effort to re-instate them.
15.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
│
│ 1.02 : (5 July 1990)
│ - added highlighting of keywords and found text
│ - changed index file extent from .IDX to .ARI
│
│ 1.03 : (6 July 1990)
│ - added procedural make.
│ - support for 43-line and 50-line screens.
│ - added alpha sort for chapters
│ - added stand-alone make utility
│
│ 1.04 : (14 July 1990)
│ - added F1 function key for Help
│ - added F5 function key for Last Find
│ - added F6 function key for Jump to Next Chapter Stop
│ - fixed Upper/Lower case problem with highlighting
│ - fixed bug with files of longer than 32k lines
│ - added Crawl Read
│
│ 1.05 : (23 July 1990)
│ - added UpperCase make and set up Make sub-menu
│ - increased maximum chapter stops to 500
│
│ 1.06 : (1 August 1990)
│ - added F7 function for instant Add Chapter
│ - added Page Find function
│
│ 1.07 : (6 August 1990)
│ - added Dump function
│ - added F5 for Find Text, rearranged other function keys
│
│ 1.08 : (20 September 1990)
│ - fixed bug preventing last line of file being seen
│ - added saving of screen colours to .ARD file
│ - added screen offset feature
│ - improved indexing procedure
│
Autoread Manual -32-
│ - added Alt-Q - Quit Without Data Save
│ - added Remove Duplicates to Chapter Menu
│
│ 1.09 : (28 March 1991)
│ - changed file indexing procedure, to fix errors some users getting
│ with old method.
│
│ 1.10 : (19 October 1991)
│ - added file buffering
│ - added In Chapter Find (find text in chapter heading)
│ - added -F find text command-line option
│ - altered format of .ARD file
│ - added New Page option to Dump menu
│ - altered Bookmark display (now includes first text on marked lines)
│ - altered Last Session handling (now places bookmark instead of
│ immediate jump)
│
│ 2.00 : (11 December 1992)
│ - Complete rewrite
│ - Much better user interface: mouse control, scroll bars, standard
│ menu behaviour. Menu options always visible.
│ - Chapter, Keywords and Bookmarks windows moveable and resizable.
│ Also now retain their current scrolled position.
│ - Dialog boxes now offer greater choice without having to ask a series
│ of tedious questions.
│ - Much larger documents can be accessed - anticipated (but not tested)
│ to be able to handle files of in excess of 2 million lines. (Note
│ that only the registered version has this capability)
│ - No limits (in registered version) to number of chapter stops or
│ keywords, within available memory.
│ - Chapter descriptions no longer limited to 40 characters wide.
│ - Easy alteration to 43/50 screen line display through Utilities.
│ - Bookmarks can now optionally be saved.
│ - Behaviour of Autoread for a particular document can be altered
│ through Preferences.
│ - Now keeps track of whether .ARD file needs to be re-saved.
│ - Index (.ARI), Data (.ARD) and Bookmarks (.ARB) files can optionally
│ reside in a different directory to the document file. This allows
│ AUTOREAD to be used on documents residing on read-only or write-
│ protected disks (for example, with text documents residing on CD-ROM).
│ - AUTOREAD can be left running while documents are closed and opened.
│ - Document selection through standard dialog box.
│
│ 2.01 : (10 May 1993)
│ - A number of bugs in 2.00 fixed.
│ - Promote and Demote levels added
│ - Changed behaviour of Chapter, Keyword and Bookmarks windows after a
│ find entry (document window now automatically selected).
│
│ 2.02 : (8 June 1993)
│ - Fixed a bug in Uppercase Make
│ - Added warning on ESC from Document Window
│ - Added Centred Make
│
│ DRAWBACKS/OMISSIONS in Version 2.0x:
│
│ - Screen colours no longer selectable (this will be provided in future
│ versions).
│ - "Crawl Read" not currently supported.
│ - Executable file is now much bigger ~160k rather than ~60k.
Autoread Manual -33-
APPENDIX A: FUNCTION KEY SUMMARY
════════════════════════════════
F1: Help
F2: View Chapter List
F3: View Keyword List
F4: View Bookmark List
F5: Text Find
F6: Repeat Last Keyword or Text Find
F8: Jump to Next Chapter Heading
Ctrl-F5: Find Text in Chapter Heading
Ctrl-F6: Repeat Chapter Find
Alt-A: Add current line as Chapter
Alt-X: Quit Autoread
ESC: Close Current Window
Shift-F1
Thru : Set Corresponding Bookmark
Shift-F9
Alt-F1
Thru : Jump to Corresponding Bookmark
Alt-F9
Autoread Manual -34-
APPENDIX B: COMMAND-LINE OPTIONS
════════════════════════════════
To use a command-line option, append the desired option (which must
begin with a hyphen) to the command line you use to start up AUTOREAD,
eg:
AUTOREAD MANUAL.DOC -X -Y
Note that you cannot use command-line options UNLESS you are starting
up a document on the command line. That is, a line like:
AUTOREAD -X -Y
...will simply ignore the command line options.
The current command-line options are described below.
-F"Search Text":
This allows you to start AUTOREAD and immediately carry out a
search for some topic. Note that the text should be in quotes if it
includes a space. Note also that this option starts by searching the
Chapter list for the topic, and if found, it will go straight to that
chapter stop. If the topic text cannot be found in the chapter
descriptions, AUTOREAD will start to search the whole text of the
document. This facility is very useful for setting up "Help" systems.
-Idirectory
-Ddirectory
-Bdirectory
These options let you specify the directories where AUTOREAD will
look for the document Index (.ARI), Data (.ARD) and Bookmark (.ARB)
files respectively. The default in each case is the same directory as
the source document.
Autoread Manual -35-
APPENDIX C: THE .ARD FILE FORMAT
════════════════════════════════
It's often worthwhile using a text editor directly on the .ARD file in
order to tidy things up, quickly remove invalid chapter stops which
were created by Make, and so on. You can also capture the index pages
of the original document and massage them into a list of keywords,
which you can directly append to the .ARD file.
The .ARD file is just an ordinary text file.
The following applies to Version 2.00 of the software. There have
been some changes since version 1.10, but AUTOREAD will still read
version 1.10 .ARD files. It will not, however, read .ARD files from
earlier versions. However, it is a simple matter to convert these
earlier .ARD files to the new format.
The file is marked off into sections, each with a header of the form:
#[section name]. These headers are then followed by lines of data.
Here is a sample .ARD file:
#[SCREEN]
0/0/0/0
#[PAGE NUMBERS]
Gryll Grange Page -/50
Page -/0
0
#[PREFERENCES]
L/0/N/N/Y/Y/-/
#[MISCDONE]
#[CHAPTERS]
Prologue/211/1
Chapter One/425/1
Intermezzo/534/2
Chapter Two/678/1
Epilogue/1009/1
#[KEYWORDS]
bravery
lust
passion
romance
woe
Let's look at each section in turn.
The #[SCREEN] section is currently unused, but in future versions of
AUTOREAD will be used to store screen colours and possibly some other
information.
The #[PAGE NUMBERS] section is of the following form:
Autoread Manual -36-
MyManual p./69
MyManual/12
0
where the text before the slash is the text that AUTOREAD uses to
check that it has found a page numbering line, and the number after
the slash is the column number near where AUTOREAD will check for the
wanted page number in the page numbering line. If no page templates have
been set, then these numbers will be -1 for both odd and even pages.
The third line in this section indicates the page size, if the page
numbering has been indicated to be at the bottom of the page.
The next section, #[PREFERENCES] of course stores the preferences you
have selected for the document, in the following order:
Item 1: L or A: Indicates Line or Alpha sort order
Item 2: Screen offset - an integer
Item 3: Save Last Session - Y or N
Item 4: Start At Last Session - Y or N
Item 5: Save Bookmarks - Y or N
Item 6: Show Level Prefixes - Y or N
Item 7: Level Prefix characters - ASCII text.
#[MISCDONE] simply speeds up processing by telling AUTOREAD that this
is the end of its miscellaneous information before it hits the
Chapters and Keywords. You can cut it out without any problems, but
it may slightly slow down document loading.
#[CHAPTERS] is of course the header for the list of chapter stops, all
of which are in the following format:
│ 1.0 INTRODUCTION/25/1
The text is of course the chapter description text, and
the first number following the slash is the line number where the
chapter begins. The second number is the level of the chapter.
The #[KEYWORDS] section is of course the list of keywords, in
alphabetical order.
If you want to manipulate the .ARD file, feel free to do so. It is
easy to simply delete or add keywords, or to delete erroneous chapter
stops. Note however that you will need to know the line number if you
wish to add chapter stops. The sections in the .ARD file should be in
the order shown; in particular, the KEYWORDS section must follow the
CHAPTERS section.
Autoread Manual -37-
APPENDIX D: LIMITATIONS OF AUTOREAD
═══════════════════════════════════
AUTOREAD, like most things, is not perfect. It has limitations.
However, version 2.00 lifts a lot of the previous limitations on size
- provided you register your copy!
Version 2.00 (registered) allows the handling of files up to 2,100,000
lines in length. A typical text file with this many lines would be
around 80MB in size!! The unregistered version lets you handle files
of only up to 30,000 lines.
There are no limitations on the number of chapter stops or keywords in
the registered version, other than those due to memory limitations.
On a 640K machine, you should be able to set thousands of chapter
stops with no problems. Again, however, the unregistered version sets
limits - 400 chapter stops and 100 keywords. What a good reason to
register!
AUTOREAD also has no way of determining if a file you are trying to
use it on is in fact a text file. It will do very weird things if you
use it on a binary file such as an .EXE file, for example. If you
need to examine binary files, use the Norton Utilities or LIST.
AUTOREAD will also get very confused if you feed it files with very
long lines. AUTOREAD can at least handle without confusion files
which include lines of up to 255 characters. Any more than that, and
AUTOREAD loses track of the beginnings of lines.
Autoread Manual -38-
APPENDIX E: MUSINGS ON THE WRITING OF MANUALS
═════════════════════════════════════════════
I guess I was naive when I first set out to create AUTOREAD. I
figured that most text file manuals would follow a similar sort of
format. Alas! It is now clear that there are as many styles of
manual as there are authors.
This makes creating a utility like this one which will be able to do
such stuff as automatically creating chapter stops very difficult.
It amazes me that some authors create manuals where the section
headings are barely given ANY kind of distinction from the rest of the
body text. No underlinings, no section numberings, not even all in
caps. Surely this makes these manuals difficult to read even in a
hard copy printout?
The same goes (in spades) for different ways of indicating page
numbers.
I guess this is a (selfish) plea for well designed manuals that
AUTOREAD will work well with!
Autoread Manual -39-
APPENDIX F: UPGRADING TO VERSION 2.0x
═════════════════════════════════════
I hope that you will find upgrading from earlier versions of AUTOREAD
to be fairly painless. The main questions I have had from users relate
to how the new interface works:
* The ESC key no longer toggles to the menubar - Alt F10 does this,
and ESC now closes windows, including the main document window,
though it will prompt to check on this.
* The Chapter, Keyword and Bookmarks menus are inactive unless the
relevant window is active. To access the choices on the Chapter
menu, press F2 first. For Keywords, press F3. For Bookmarks, F4.
I personally find that I use the 'hot-key' equivalents far more
than I use the menus.
* All windows are re-sizable by using the mouse to drag the bottom
right corner of the window where you want it.
F.1 Converting old .ARD files
─────────────────────────────────────────────────────────────────────
If you are upgrading to version 2.0x of AUTOREAD from a version prior
to version 1.10, then you will need to convert your old .ARD files to
be usable by the new version.
To make this easy, I have now provided a utility called CONVARD.EXE.
To convert your old .ARD file, eg MANUAL.ARD, just run the utility
from the command line like this:
CONVARD MANUAL
This converts the data quickly, saving your old .ARD file into a file
called MANUAL.AR$ for safety. You can delete this .AR$ file once you
are happy that AUTOREAD is now working with your old data.
Autoread Manual -40-
APPENDIX G: RAVE REVIEWS AND UNSOLICITED TESTIMONIALS!
══════════════════════════════════════════════════════
"splendidly designed and immensely powerful... this little gem...
we'll bet you'll soon be in love with this splendid piece of
shareware."
----- "Boardwatch Magazine", November 1991:
"Again thank you. Your product is a life saver for me..."
----- Shaw and Associates:
"excellent product/idea!"
----- Lowell D.King
"You've invented a great concept!"
----- Dan Pichulo
"...very impressed...your idea of chapter location is an
innovative feature..."
----- Scott Robertson
