home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
World of Shareware - Software Farm 2
/
wosw_2.zip
/
wosw_2
/
GENERAL
/
TG120.ZIP
/
GUIDE.NEW
< prev
next >
Wrap
Text File
|
1993-03-24
|
33KB
|
701 lines
%t Guide! Documentation File
%n 2R1
%s GUIDE.DOC converted into a valid entry for your pleasure
%a Steve Baker (swbaker@vela.acs.oakland.edu)
%d 19930302
%f FACT
%i Documentation for The Guide!
%i GUIDE.DOC file
%x Article Writing Guide For Field Researchers And Guide Editors
%x Guide! Information
%e
The Guide!
an experiment in Turbo Vision/OOP to implement
The HitchHiker's Guide to the Known Galaxy
developed and written by Steve Baker
Our Shadow's SoftWorks
> swbaker@vela.acs.oakland.edu <
Initial Release Documentation
slightly revised 03/02/93
0.0 Legal Stuff
This system is Copyright (c) 1992-1993 Steve Baker, Our Shadow's
SoftWorks. Permission is granted to any individual or institution
to use, copy, or redistribute these executables and associated files
so long as they are not modified and that they are not sold for profit
(hence the motto, "Share and Enjoy!").
The TG! system is provided "as is" and comes with no warranty of any
kind, either expressed or implied. In no event will the copyright
holders be liable for any damages resulting from the use of this
software.
There, got that stuff out of the way. Now then, if you *do* discover
any glitches and/or problems, please feel free to email them, along
with a complete description of your PC system and configuration, to
me (swbaker@vela.acs.oakland.edu). I will do my very best to resolve
any problems that are discovered.
1.0 Introduction
Many virtual eons ago, Douglas Adams wrote some radio scripts for a
new radio humor series entitled _The Hitchhiker's Guide to the Galaxy_.
In the shows (which have evolved into a series of novels, TV episodes,
records and CD's, and even computer games), the heroes "consult the
Guide," the best-selling book with "Don't Panic" inscribed in large,
friendly letters on the cover, in times of duress.
Since then, the concept of consulting an on-line electronic
encyclopedia-like Guide while exploring the (known) universe has
intrigued and baffled mankind.
Until now.
The Guide! is my "vision" of the Hitchhiker's Guide: a DOS-based
article consultation system, similar to the "real" Hitchhiker's Guide
that Ford and Arthur consult whilst exploring the universe (suitable
for use on laptop/palmtop systems as well as full desktop and network
environments). With TG!, the roving hitchhiker can search for, read,
print, and capture to disk the life-saving articles that roving hitch-
hikers have come to expect from the Project Galactic-Guide staff.
1.01 Overview
Before we start, let me mention that if you're impatient and want to
get going with this thing, take a look at a file called READ.ME which
describes the steps required to get up-and-running. Anyway...
The Guide! is a full-featured, multi-windowed, pop-up and pull-down
menu'ed, mouse-supporting anomaly. It reads in new entry articles
from standard ASCII files, and supports multiple entries per .NEW
input file (archive).
TG! features a nifty search and query engine, allowing the user to
search in many different ways. The following are verbose examples of
searches you may request:
* Give me all entries which have the word "wazoo" in the title, are
written by Joe Schmoe, and are completely real.
* Show me all entries written between Date1 and Date2.
* I want any articles with "meatball" in the summary, written
before Date1, which are both real and unreal.
... and any combination of title, summary, author, date, and reality
(being real, unreal, or semi-real) imagineable.
As one would expect from an encyclopediac-type device, TG! offers a
Table of Contents, a full Index, author and editor biographies, and
cross-references which link articles together (if an article has cross-
references to a second article which has not yet been added to the
system, The Guide! is aware of that "incomplete" xref and will update
it, automatically, when the second article is eventually added).
1.1 Moving around in The Guide!
TG! features what is becoming an industry-standard user interface.
This interface is comprised of three parts:
1) the pull-down menu bar, at the top line of the screen
2) the main "desktop" area, in the middle of the screen
3) the status-line bar, at the bottom line of the screen
The Guide! is great for those with a mouse, and is also easy to use
with the keyboard. Access the menu bar by either pressing [F10], or
clicking the [ The Guide! ] "button" on the status bar, or by pressing
one of the Alt-letters (ie, [ Alt-F ] for the [F]ile menu, etc).
Numerous hot-keys have been defined which bypass the menu structure
and invoke the desired function directly. These hot-keys are listed
along side of the functions they invoke in the pull-down menus; browse
through the pull-down menu bar to note these functions. Here are some
of the highlights:
[F2] Define title, summary, author, and factuality
search parameters, without evoking a search
[F3] Define date search parameters
[F4] Consult the Index of the current GuideNET base
[Alt-F3] Close active window
[F5] Zoom/unzoom active window
[F6] Activate next available window
[Shift-F6] Activate previous available window
[F7] Browse forward from current location
[Ctrl-F7] Browse backward from current location
[F8] Define title, summary, author, and factuality
search parameters, and begin a new search at the
beginning of the GuideNET base
[F9] Continue using results of most recent search
[Alt-L] Load a new GuideNET base
[Alt-P] Print the current article
[Alt-T] Consult the Table of Contents
[Alt-V] Save the current article as an ASCII text file
[Alt-X] Exit The Guide!
Many functions bring up dialog boxes with modifiable data fields.
Common ways to maneuver through these dialog boxes:
* [TAB] moves forward one option or field
* [Shift-TAB] moves backward one option/field
* cursor/arrow keys moves the "radio-buttons" options around
* the space bar toggles the "check-box" items
* [Enter] (or click the [Ok] button) to proceed
* [Esc] (or click the [Cancel] button) to abort the process
(where applicable)
Mouse users may click the various "buttons" on the status line at the
bottom of the screen. For example, the [ --> ] button is the "Browse
forward" ([F7]) command, and the [ <-- ] button is the "Browse backward"
([Ctrl-F7]) command. Also, you may click on the functions described
on the status line (ie, click anywhere on the "F4 Index" to bring up
the index, etc).
... This is pretty much standard stuff, for those who've dealt with
these types of interfaces before. As mentioned earlier, this type of
interface is becoming an industry-standard, with more and more packages
adopting this consistant interface.
2.0 Adding entries to The Guide!
The Guide! is designed to be very flexible with its data input. It
will read in as many new archive files (files which contain articles)
as you want to throw at it, providing they meet these criteria:
1. The articles must conform to the current format standards.
These are described in the article "Article Writing Guide for
Field Researchers and Guide Editors" (available in TGxxx.ZIP as
FORMATS.NEW). This paper describes the proper formatting and
article fields agreed upon by Project Galactic-Guide.
(See section 2.1, below, for more info on this stuff.)
2. Each ASCII file must end with a [ .NEW ] extension, ie:
FOO.NEW
BAR.NEW
This way, whole batches of files may be processed at once,
following the simple idea that every .NEW file shall be added
to the system (ie, these are the "new" articles to add).
3. Multiple entries may reside in a single ASCII file, but every
article MUST be terminated (ended) with this special flag:
*EOA*
which means "End Of Article." This flag must appear in the
FIRST column of a line, and must be the only item on the line.
Of course, you want this *EOA* flag to be AFTER the article,
not before or somewhere inbetween.
Available system memory cannot be exceeded. The Guide! has built-in
protection against "out of memory" crashes, and can perform partial
updates (ie, read in some, but not all, of the articles available)
if memory becomes low.
To avoid memory problems, and to allow greater organization of
articles into logical collections, TG! supports multiple GuideNET base
files. Thus, when one GuideNET base becomes full, simply begin another
one, analogus to starting a new volume of an encyclopedia when the
current one becomes "full."
The Guide! offers several ways of handling these .NEW files --
1. Rename - the system changes their extension to [ .OLD ], so
they are not processed again, but are still available if
required (this is the system default).
2. Delete - the files are usually no longer necessary once
the articles have been loaded, and can safely be deleted to
free up additional disk space.
3. Preserve - any .NEW files found and processed will be preserved
as .NEW files. A note of caution - when this is used, you may
inadvertantly load in the same data every time you update,
since all files with a .NEW extension are processed (and if
they are not changed to something else, they could be
processed again the next time you Update your GuideNET).
Update options and user-interaction are fully supported. In
particular, you may:
1. Automatically accept each and every article found, including
duplicate articles. If a new article has a title which is
already in the GuideNET, a special message is appended to the
new title. This ", Entry x" message denotes that the article
is the 2nd, or 3rd, or xth, article with the same title.
(See Section 2.3, below, for more info on this ", Entry x"
message.)
2. Automatically accept only new, unique articles, and skip any
duplicate articles found (ie, if an article already exists in
memory, then skip any new, incoming articles with the same
title).
3. Accept new articles, and also automatically update existing
articles with data from new articles with matching titles
(if any are found).
When this occurs, all indexes and out-going cross-references
associated with the "old" article are removed, and the new
article's indexes and out-going cross-references are inserted
in their place. Any in-coming cross-references to the
article remain intact.
4. Manually decide whether or not to accept each article found.
You are shown the new article's title, summary, author, date,
and factuality. At this point, you may choose to [A]ccept
or [S]kip the article.
When you accept an article with the same title as an entry
already in the current GuideNET, the ", Entry x" flag is
appended (see above).
General observations:
Each new article is "stamped" with a unique identification field
when it is approved by an editor. This ID field (%n) is the only
way that a given article can be distinguished from other articles,
particularlly if they have the same title.
When an existing article is updated (for example, the author has
done some more field research, or an editor decided he didn't
really like that last bit as much as he thought he did, etc), the
system updates the GuideNET base with the revised article. This
updating is performed automatically and transparently by TG!.
2.1 Format of new entry files
The Guide! reads ASCII entry files which conform to the "Article
Writing Guide..." paper which is frequently posted on the Internet
newsgroup alt.galactic-guide. The writing guide is also included in
this collection as the file FORMATS.NEW.
Several extensions have been added to this format, which I believe
have been mentioned in the newsgroup:
* %f [ REAL | UNREAL | SEMI-REAL ]
- this is my preferred way of handling "reality"
* %f [ -10 .. 10 ]
Another suggested way of handling factuality. These are
converted as follows:
-10..-4 : UNREAL
-3..3 : SEMI-REAL
4..10 : REAL
* Of course, if a 'U', 'R', or 'S' is present in the %n <id number>
field, then that'll work also ('U' = UNREAL, 'R' = REAL, and
'S' = SEMI-REAL ).
In general, the case of the field identifiers is not sensitive (ie,
you can use either '%t' or '%T' for the Title identifier).
Recall that The Guide! uses the special marker [ *EOA* ] to define a
"break" between articles in an "archive" .NEW file (one which contains
more than one entry). Of course, this *EOA* should not appear anywhere
other than BETWEEN complete articles.
This special marker is required since TG! does not force any
particular ordering to the field tokens. That is, the order of
the markers is not strictly important (with one exception; the
[ %t ] title marker MUST be the first field), so the system needs
a signal that the article has indeed ended.
The Guide! ignores any non-key lines in the input files. This way,
users can simply capture new articles from the newsgroups, save them
as ASCII files, and let the system handle the rest. Comments, remarks,
etc. may also be inserted before, between, and after articles. These
will also be ignored.
See the sample .NEW files for examples of these flexibilities.
2.2 Adding new entries into the system (using UPDATE.EXE)
There are two methods to add new articles to the system; automatically
(via the Auto-Pilot) and interactively (via dialog boxes, etc). Both
functions are performed by a program called Update (UPDATE.EXE).
Consult the file READ.ME for quick, let-me-get-going information on
adding articles to the system.
2.21 Automatic article inclusion
At the DOS prompt (and in the appropriate sub-directory, ie C:\GUIDE),
type [ UPDATE /AUTO ]. The system will process the supplied articles,
and then return to the DOS prompt.
Data loading may take a few minutes (especially on slower systems,
and those without disk caching). GuideNET Update displays a status
window to show its progress (ie, what entry number, file name, and
article name it's currently processing).
When the program has finished, Update displays the number of articles
added into the system.
2.22 Interactive article inclusion
At the DOS prompt, type [ UPDATE ] to load the Update utility program.
Pull down the <U>tility menu, and select <U>pdate (or simply press F4).
The first time you perform an update, the system will first ask you to
define the GuideNET NAME and DESCRIPTION. This information is required
for TG! to proceed. The name must be eight characters or less (and a
valid DOS filename), while the description can be up to fifty characters
of any nature. A default name (GUIDE) and description are displayed,
unless overridden.
Next, GuideNET Update displays the Update dialog box. This box has
several Options and Toggles, most of which are described in Section
2.0, above. If you desire, modify these options and toggles. Then,
press [O]k (or Enter) to proceed, or [C]ancel (or Esc) to quit.
The data-loading process may take a few moments, especially on slower
systems, and those without hard disk caching (see Section 5.0,
Optimizing, below). The Guide! displays a status window displaying its
progress (ie, what new entry number, file name, and article name it's
currently processing).
When it's finished, The Guide! displays how many articles were added
to the current GuideNET. Before exiting the system, be sure to save
your data by either pressing [F3] (Save) or by using the <F>ile | <S>ave
pull-down menu function.
2.3 Duplicate entries, indexs, and cross-references (in UPDATE.EXE)
Duplicate entries are incoming articles which have titles that are
already in the system (thus, they are called "duplicates" even if the
articles themselves are completely different, and the fact that the
titles are the same may be "purely coincidental").
TG! allows duplicate entries, indexs, and cross-references. It
takes care of all the busywork, and lets you get on with using TG!.
The Guide! distinguishes between original entries and subsequent
duplicates (if allowed into the system; see 2.0 above) by appending the
phrase ", Entry x" to the duplicate's title.
For example, if an article entitled "Gallifrey" already exists in the
system, and another article with the same title is added to the system,
TG! will modify the second title so that it becomes "Gallifrey, Entry 2"
and so on.
Any index and cross-reference links to duplicate entries access that
duplicate entry, just as any index and cross-reference links to the
original entry access that original entry. From the article displayed,
you may Browse forward/backward to other duplicate entries.
UPDATE.EXE is now especially aware of UPDATED articles. These are
pieces which were previously released, but have since been updated with
new information. TG! (via the GuideNET Update program) now auto-
magically updates any existing articles with their new replacements,
as they arive.
This is possible since each article must have a UNIQUE %n (ID)
field. Thus, if a "new" incoming article has the same %n field
as an article already in the GuideNET, then it MUST be the same
article. To determine if the "new" one is really newer than the
existing article, their dates are compared. If the "new" article
has a more recent date, then the update is performed. Otherwise,
the "new" article is discarded (since you presumingly have a newer
version of the article already in the GuideNET).
2.4 Saving the data (in UPDATE.EXE)
The Guide! supports multiple data files, and each file may have a
50-character description associated with it. Thus, you may maintain
several GuideNET files by choosing Manual Control in the Update option,
and selecting desired articles for each collection.
The GuideNET name and description were defined before the system
performed the updating process. If you wish to rename the current
GuideNET file, you may use the "Save [A]s..." function, in the <F>ile
pull-down menu, to modify the name and description.
Before you exit UPDATE.EXE, you should save the updated GuideNET file
information either by pressing [F3] or by using one of the Save
commands from the <F>ile pull-down menu.
3.0 Search and query (in GUIDE.EXE)
These functions are performed in the GUIDE.EXE article reader program.
At the DOS prompt, type [ GUIDE ] to load the program. After the
welcoming "Don't Panic!" title screen, you will see the GuideNET
index. Press [Esc] or click on the [ Cancel ] button to bypass
this screen.
Pull down the <S>earch | <G>o! menu, or use the hot-key F8, to define
the various search parameters you wish to use. These parameters can
even be saved so you may restore them later.
Note that these parameters are conjunctive; that is, if you define a
string for specific titles (ie, "Bob") AND a particular author string
(ie, "Joe"), then the search will return only the artitles with "Bob"
somewhere in its title AND "Joe" somewhere in the author field, not
EITHER. Thus, the more parameters you define, the more specific your
search becomes.
Selecting "Go!" first displays the Define Search Parameters dialog
box, which is used to narrow the search. When you press [Enter] or
G[O], the system generates the complete list of all entries which match
your current Search parameters. This list is presented in a dialog
box, from which you may select the desired article(s).
"Continue" will display the current list of matching articles, which
was generated with the most recent "Go!" command. This option does not
re-generate the matching articles list; it simply allows you to proceed
with the current match list.
The index and cross-references, as well as both forward and backward
browsing, are accessed through the <C>onsult menu, and also through
their respective hot-keys. In addition, "Browse backward/forward"
buttons are defined on the bottom "status line" for mouse-users.
The index list, cross-reference list, table of contents, and search
results list are shown in "list-boxes". These list-boxes support
multiple-key "speed searching." Thus, if you press either [ R ] or
[ r ], the highlight bar moves to the first entry beginning with the
letter "R" (if available). Then, pressing [ I ] or [ i ] moves the
highlight bar to the first entry beginning with "RI" (if availble),
etc. Press any non-character key (ie, Backspace, Arrow keys,
Home/End/PgUp/PgDn, etc) to clear the search buffer.
4.0 Print and save
You can print and save the active entry (ie, the current on-screen
article, which is "active" with its window boarder highlighted). The
output of Print and Save (both accessed from the <W>indow menu, and
also via hot-keys) is similar to what is diaplayed on-screen.
"Print" formats the article with margins, and sends it to the port of
your choice: LPT1, LPT2, or LPT3. The default is LPT1. (This output
can be redirected to one of the COM, ie serial, ports by using the MODE
command supplied with DOS.)
Three "check-box" options are available in the Print dialog box --
1. Page numbers may be added to the bottom of each page. The
default is 'on', which does print page numbers.
2. "Graphical" lines may be used instead of ASCII lines. The
default is 'on', which enables graphics characters.
3. Compressed printing (132 col) instead of normal print (80 col).
The default is 'off', which retains normal printing.
In addition, you may specify the appropriate printer type at the bottom
of the Print dialog. In particular, TG! supports dot-matrix printers
(which are compatable with the IBM ProPrinter) and laser printers (which
are compatable with the HP LaserJet series). The default is dot-matrix.
The print engine in TG! automatically enables the Compressed Printing
option if the article exceeds 80 characters in width; likewise, it
disables the option if compressed print is not required. You may
always over-ride this default before clicking/selecting Ok.
"Save" asks you for a destination file name, which is created as a
standard ASCII file.
5.0 Optimizing The Guide!
The Guide! does not like to work on floppy-disks. Thus, PLEASE install
the system on your hard disk. However, if you insist on diskettes,
TG! is operational, but is rather S-L-O-W (because of the very poor
access times of diskettes).
5.1 Hard disk stuff
The Guide! performs a lot of disk reads and writes, as it retrieves its
data. Thus, I STRONGLY recommend that those with EMS/XMS memory use a
disk-caching utility to improve disk access. DOS 4 & 5 ship with one
("SmartDrive"), but third-party utilities are much better.
Blatant but unreimbursed plug:
I use the Norton Utility 6.0's Norton Cache, since it can perform
disk writes IN THE BACKGROUND after telling the program that the
writing is done; thus, TG! completes its Updating VERY QUICKLY
since it doesn't have to wait for the disk writing to be completed
(the cache does all the writing in one big chunk, instead of file-
by-file, in the background after a specified time-delay).
The SMARTDRV.EXE version 4.0, which ships with the new MS Windows
3.1, also supports this write-behind feature, but I prefer NC for
other reasons as well.
5.2 Memory stuff
As far as memory itself goes, PLEASE upgrade to DOS 5.0 (or else stick
with DOS 3.3, if you don't have a 286/386/486, etc) and try to give
yourself as much memory as possible (by either loading your TSR's, etc
into high memory, or not load 'em at all). Also, other optimizations
can be made in your CONFIG.SYS (exmaples: reduce Buffers to 5 or 10 if
you use a disk-cache; reduce Stacks to 0,0 unless Windows complains;
set LastDrive to the last drive you really use, like D or E; etc).
Consult your DOS manual for tips on how to optimize your system (my 386
has 635k free conventional memory, cos everything's pretty much optimal
in the UMB's). I recommend third-party memory-management software,
like Quarterdeck's QEMM 6.02, instead of DOS's HIMEM and EMM386.
6.0 Testimonials...
(written by fellow TG! user Ronald Larsen, of Oregon, USA)
Other Uses for the The Guide! software:
---------------------------------------
In a network environment, The Guide! can be an extremely
astoundingly useful program to provide documentation for network
setups, help files, and other inestimable information. In one
such lab (deliberate plug: the Social Sciences Instructional Lab
at the University of Oregon), The Guide! has been used for just
this purpose. Our purpose in using an on-line information source
like The Guide! is to provide quick (and [hopefully] organized)
troubleshooting information for lab staff, and to provide a basic
training source for new lab staff. The Guide! has even proven
robust enough to survive the savageries of windows. To spread
out our limited knowledge as far as possible, we allow all users
in the Lab to access and browse through The Guide! articles.
In place of the articles -- with two exceptions -- that come with
the program (conventently located at an FTP site near you), new
articles have been written covering such topics as: Hours of
Operation, Network Configuration, Conventions of Naming Users,
Policies on Assigning Rights to Users and Groups, etc. The
exceptional articles retained from the original group of articles
are The Guide! documentation and the article outlining the format
of articles. The former is retained for obvious reasons. The
latter is to encourage lab staff and other concerned citizens to
contribute articles to the network supervisor for inclusion.
On the technical side (running Netware 3.11), The Guide! is
located in a sub-directory off the first network drive, flagged
as READ-ONLY. All users may Read and Scan these files, rights
assigned to the EVERYONE group. The UPDATE.EXE file is kept in a
sub-directory where only the supervisor has access. A general
master archive file, for use with a normal word processor, is
also kept in this directory. New and modified articles are cut
and pasted into a new update file. When updating The Guide!, the
READ-ONLY flags are removed, and UPDATE.EXE and the updated
articles file are copied back into this sub-directory (done
through a batch file). UPDATE is then run, taking advantage of
the Numbered Update option. When the Update is done, the files
copied from elsewhere are deleted and the Read-Only flag is re-
set on all files.
In our use of The Guide!, due to the sheer number of articles,
there are four GuideNets, named: Hardware, Netware, Policies,
and Software.
HARDWARE: We use this guide to cover topics relating only to the
hardware in the lab. Currently, this includes: (a) inventories
with serial numbers and configurations; (b) possible problems
with the hardware (especially the &$#+^%@(* printers); and (c)
how to connect occasional equipment (such as a screen projector).
NETWARE: This GuideNet covers our specific configuration, such
as the various NLMs we normally load, Printer Configurations, and
other trivialities.
POLICIES: The GuideNet is required reading for all lab staff.
In this GuideNet, we cover all the policies they are expected to
follow; such as: (a) Closing Procedures; (b) various charges
and rates for materials or services; (c) hours; and (d) general
conduct in the Lab.
SOFTWARE: None of the articles are meant to replace any of the
manuals or other software documentation that normally comes with
the programs used on the network; rather, the articles that
cover specific programs discuss: (a) the special tweaking that
was necessary to get the program to run on the network; (b)
specific problems encountered in running a program, and if known,
solutions; (c) the vulgarities of the batch files that launch a
program from the users' menus; and (d) registration information
(i.e., serial number and number of licenses).
--
+--------------------------------------------------------------------------+
| Ronald Larsen | BITNET: RSLARSEN@OREGON.UOREGON.EDU |
| Social Science Instructional Lab | ccmail: Ron_Larsen@ccmail.uoregon.edu |
| 72 Prince Lucian Campbell Hall | Voice: 503 346 2547 |
| University of Oregon (OR-A-GUN) | |
| Eugene, Oregon 97403 | Personal: HEY YOU! |
+--------------------------------------------------------------------------+
7.0 Conclusions
The Guide! was written with "Borland Pascal with Objects 7.0" using the
Turbo Vision Object-Oriented Programming tools on a clone 386/33 system.
The quotes you'll see as part of the various error messages were
lifted from _The Original HitchHiker Radio Scripts_ by Douglas Adams
(with a few from his "HitchHiker's Guide" book series to boot).
I could add lotsa bells and whistles, like SoundBlaster/AdLib support,
and have it plot some nifty fractals during idle time, but I'll save
them for another day, if I even bother at all.
Well, that's it for now... let me know what you all think about this
program... please send any comments, suggestions, questions, and/or
problems to me so we can make this program a hitchhiker's necessity,
right up there with the towel!
PS, watch for "TG! for Windows" coming to FTP sites and BBS systems
near you *soon* (probably mid- to late-March, '93).
Steve
swbaker@vela.acs.oakland.edu
"Gravity brings me down..."
%e
*EOA*
*
* End of GUIDE.NEW
*