Media Share 9

home *** CD-ROM | disk | FTP | other *** search

/ Media Share 9 / MEDIASHARE_09.ISO / private / tg120.zip / GUIDE.DOC < prev next >

Wrap

Text File | 1993-03-24 | 33KB | 682 lines

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..."