Computer Buyer 1997 January

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

/ Computer Buyer 1997 January / dpcb197.iso / business / a1share / 41411.ZIP / GUIDE.OLD < prev next >

Wrap

Text File | 1993-05-25 | 55KB | 1,239 lines

%t Guide! Documentation File %n 2R1 %s GUIDE.DOC converted into an article for your pleasure %a Steve Baker (swbaker@vela.acs.oakland.edu) %d 19930525 %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 moderately revised 05/25/93 Topics --------------------------------------- 0.0 Legal Stuff 1.0 Introduction 2.0 Adding new articles into The Guide! 3.0 Search and Query 4.0 Print and Save 5.0 Optimizing The Guide! 6.0 The Guide.INI Configuration file 7.0 The Guide! and Networks 8.0 Conclusions --------------------------------------- 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, and 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 holder(s) 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 electronic 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.1 Overview Before we start, let me mention that if you're impatient and want to get going with this thing, take a look at the ASCII text file called READ.ME, which summarizes the steps required to get up-and-running. 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, indices, and reality (being either real, unreal, or semi-real) imaginable. As one would expect from an encyclopedic-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 automatically link it if/when the second article is eventually added.) 1.2 Command-line parameters Both programs have command-line parameters, which you may use to configure the programs. To view the list of available command-line parameters, load the desired program with the [ /? ] parameter. Thus, to see what you can do with Guide.EXE, type [ GUIDE /? ]. Likewise, [ UPDATE /? ] displays its help screen. The parameters for Guide.EXE are: /Help or /? ; displays DOS help screen and parameters /Mono ; loads in Monochrome, if available /43 or /50 ; loads in High-Resolution, if available /Load=[path\]filename ; specify GuideNET file to load by default /TOC ; default to Table of Contents, not Index /NoBanner ; do not display the intro title screen /NoINI ; do not update the Configuration file /ShowLoad ; brings up the Load dialog box at startup /Load=[path\]filename ; specify GuideNET file to load by default /Config=path\ ; tells TG! where to save Guide.INI, etc. The parameters for Update.EXE are: /Help or /? ; displays DOS help screen and parameters /NoBanner ; do not display the intro title screen /NoINI ; do not update the Configuration file /Auto ; load all *.NEW files via Auto-Pilot /Auto=filename ; use Auto-Pilot with [filename], not GUIDE /Config=path\ ; tells TG! where to save Guide.INI, etc. Many of the command-line parameters (like /TOC, /NoBanner, and /NoINI) can be made permanent with the Standard Options dialog box, available in the File pull-down menu. See "Using the Standard Options dialog box," Section 6.1, for more information. 1.3 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 by clicking the [ The Guide! ] "button" on the status bar, or by pressing one of the Alt+Letters (i.e., [ Alt+F ] for the [F]ile menu). 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: [F1] Display a command summary reference screen [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. These are 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" command, and the [ <-- ] button is the "Browse backward" command. You may click on the functions described on the status line (i.e., click anywhere on the "F4 Index" to bring up the index, etc.). In Guide.EXE, this status line is "context-sensitive" in that it changes to the Alt+Commands if you hold down either Alt key, the Shift+ Commands if you hold down either Shift key, and the Ctrl+Commands if you hold down either Ctrl key. While you hold one of these keys, the buttons on the status line may be selected with the mouse. 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." If you press either [ R ] or [ r ] (case is not important), 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 available), etc. Press any non-character key (i.e., the arrow keys, Home, End, PgUp, PgDn, etc.) to clear the speed-search buffer. You may disable the multiple-key speed search in the Standard Options dialog box. If disabled, single-key speed search is activated instead. ... This is pretty much standard stuff, for those who have 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 consistent interface. 2.0 Adding new articles into The Guide! --------------------------------------- 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 ASCII text file READ.ME for quick, let-me-get-going information on adding articles to the system. 2.1 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 (i.e., 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.2 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 (50) 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.5, below. 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 "Optimizing The Guide!," Section 5.0, below). The Guide! displays a status window with its progress (i.e., what new entry number, file name, and article name it's currently processing). When finished, The Guide! displays how many articles have been added to the current GuideNET. Before exiting GuideNET Update, 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, indices, and cross-references 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, indexes, 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 Section 2.6, below) 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 will access the original 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 arrive. 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 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. 2.5 Inside the Update Process 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 ARTICLE.NEW). This paper describes the proper formatting and article fields agreed upon by Project Galactic-Guide. 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 (i.e., 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 in between. Available system memory cannot be exceeded. The Guide! has built-in protection against "out of memory" crashes, and can perform partial updates (i.e., 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, analogous to starting a new volume of an encyclopedia when the current one becomes "full." 2.6 Update dialog box options The Guide! offers several ways of handling these .NEW files. The following items, dealing with the .NEW files, can be selected in the Update dialog box: 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 inadvertently 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. 2. Automatically accept only new, unique articles, and skip any duplicate articles found (i.e., 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, particularly 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.7 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 the TGxxx.ZIP collection as the file ARTICLE.NEW. Several extensions have been added to this format, which I believe have been mentioned in the alt.galactic-guide 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 will work as well ('U' = UNREAL, 'R' = REAL, and 'S' = SEMI-REAL ). In general, the case of the field identifiers is not sensitive (i.e., 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.8 Reporting information about Articles, Indices, and Cross-References Update.EXE can generate several useful reports. These reports list information on articles, indices, and cross-references. The functions to create these reports are available in the Reports pull-down menu. The report generator creates an ASCII output file which contains the desired report information, and this file is subsequently displayed on-screen. This file may then be printed, just like a regular GuideNET article. The Article report lists the following information for each article: title, ID number, date, offset, number of frames, number of indices, and number of cross-references. Totals for each category are recorded at the bottom of the report when appropriate. The offset and number of frames information is usually required for debugging purposes only. The Indices report lists all index items, and the article titles associated with each index. Totals are recorded at the bottom of the report. The Cross-References report lists all cross-reference information by showing the "From" article title and the "To" article title, which together form a cross-reference. Totals are recorded at the bottom of the report. 2.9 Deleting Articles, Indices, and Cross-References Update.EXE provides you with delete functions for articles, indices, and cross-references. These are accessible in the Delete pull-down menu. The system displays a dialog box listing all available entries (either article titles, index items, or cross-references, depending on which function is selected), and will prompt you to verify your decision to delete the item before it is actually deleted. When an article is deleted, all associated index items and outgoing cross-references (i.e., references from the deleted article to other articles) are also removed. Note that any incoming cross-references (i.e., references from an existing article to the deleted article) will be preserved, should the deleted article be added again later. 2.10 Packing the GuideNET When a GuideNET is "packed," all fragmentation within the GuideNET is removed. Thus, the size of the file is minimized and the access time of the file is optimized. After deleting an article, and also after certain updates, the GuideNET information will require packing. The Pack function is available in the Utility pull-down menu of Update.EXE. The system will automatically pack the GuideNET after updating is complete (if required), but you must invoke the Pack function if you delete an article. 3.0 Search and Query -------------------- 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 item, 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 use them in a later session. Note that these parameters are conjunctive; that is, if you define a string for specific topics (i.e., "Bob") AND a particular author string (i.e., "Joe"), then the search will return only the articles with "Bob" somewhere in its title, summary, or indices, 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. 4.0 Print and Save ------------------ You can print and save the active entry (i.e., 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 by using the associated hot-keys) is similar to what is displayed on-screen. 4.1 Printing an article "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 (serial) ports by using the MODE command supplied with DOS.) Four "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 usually 'off', which retains normal printing. 4. Initial Extra will output an additional extra line-feed at the top of the first page. With some network print queues, the first page does not line up properly with subsequent pages; this extra line-feed is thus required for certain network print queues (like the servers in Oakland University's Kresge Library). In addition, you may specify the appropriate printer type at the bottom of the Print dialog. TG! supports both dot-matrix printers (which are compatible with the IBM ProPrinter) and laser printers (which are compatible 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 ]. 4.2 Saving an article "Save" determines an appropriate destination file name by examining the title of the current article; it then asks you to approve or modify this destination file name. The file is created as a standard ASCII file if you press [Enter] or [O]k. 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, and 6 ship with one ("SmartDrive"), but third-party utilities are usually better. Blatant and unreimbursed plug: I use the Norton Utility 7.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.x, which ships with the MS Windows 3.1 and DOS 6.0, also supports this write-behind feature, but I prefer NCACHE2 for other reasons as well. 5.2 Memory stuff As far as memory itself goes, PLEASE upgrade to DOS 5.0 or 6.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 them at all). Also, other optimizations can be made in your CONFIG.SYS (examples: 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, as everything is 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. 5.3 Windows and DESQview stuff TG! works great in both Windows and DESQview. TG! will detect DESQview and, if available, will release all idle clock cycles to the DV system. In configuring TG! for Windows or DV use, please allow a full 640k of memory for its use. TG! currently does not support EMS or XMS, so no additional memory allocations are required. 6.0 The Guide.INI Configuration file ------------------------------------ Like many applications being developed today, The Guide! has an ASCII configuration .INI file. In this file, appropriately called GUIDE.INI, you may customize the way TG! works for you. The file should be located in the program executable directory (the directory where Guide.EXE and Update.EXE are stored). Alternatively, you may tell TG! where to load and save the Guide.INI configuration file with the [ /Config=path\ ] command-line parameter. For example, the following loads Guide.EXE from C:\Guide, and the configuration file from D:\Stuff: C:\GUIDE>guide /config=d:\stuff\ (If you forget the final backslash, TG! will add it for you.) Both Guide.EXE and Update.EXE will save this configuration file when you exit either program, unless you disable the updating in the Standard Options dialog box, or use the [ /NoINI ] command-line parameter. 6.1 Using the Standard Options dialog box The Standard Options dialog box is accessible in the File pull-down menu. In this dialog box, many of the variables that are saved in the configuration file may be modified. The following sections detail the variables in the Guide.INI configuration file, the list of possible values, what they all mean, and where you can modify their values. 6.2 Standard toggles, from the set [ TRUE | FALSE ] AutoZoom If this is True, all new article windows are zoomed to full-screen. Otherwise, they are cascaded across the desktop area. This value is toggled in the Standard Options dialog box. ShowBanner If this is True, TG! will display opening "Don't Panic" screen. Otherwise, the title-screen banner is skipped. Setting this to False is equivalent to using the [ /NoBanner ] command-line parameter, and is toggled in the Standard Options dialog box. ShowReality If this is True, TG! will display the reality level of all articles in the on-screen display. Otherwise, the reality levels are not shown. This is handy for networks in which all articles are Real, and is toggled in the Standard Options dialog box. StartWithTOC If this is True, TG! will default to the Table of Contents instead of the Index for start-up consulting. Otherwise, the Index is used by default. Setting this to True is the same as using the [ /TOC ] command-line parameter, and is toggled in the Standard Options dialog box. UseMultiKey If this is True, TG! will enable its multiple-key speed-search features in the Index, Table of Contents, and Cross-References dialog boxes. Otherwise, single-key speed-search is used (this means pressing [ H ] takes you to the first item that starts with 'H', and then pressing [ R ] takes you to the first item that starts with 'R', not 'HR'. This option is toggled in the Standard Options dialog box. ShowStatusMsg If this is True, all status messages are displayed. These messages appear after actions like Printing and Save-to-disk. Otherwise, certain messages are not displayed. Critical error/status messages are always displayed, regardless of this setting. This option is toggles in the Standard Options dialog box. NetworkSync If this is True, the built-in TG! network synchronization features are enabled. See "The Guide! and Networks," Section 7.0, below. Otherwise, the network features are disabled. This option is toggled in the Standard Options dialog box. UpdateINI If this is True, TG! defaults to enable the updating of the .INI configuration file. Otherwise, TG! defaults to disable the updating. Setting this to False is the same as using the [ /NoINI ] command-line parameter, and is toggled in the Standard Options dialog box. 6.3 Printer toggles, from the set [ TRUE | FALSE ] PageCompress If this is True, TG! defaults to compressed printing. Otherwise, TG! defaults to normal (non-compressed) printing. Note that TG! will auto-detect if a given article requires page compression or not on a per-article basis. This option is toggled in the Verify Print dialog box. PageGraphics If this is True, TG! will use extended-ASCII characters for the article header information and all page numbers. Otherwise, normal ASCII characters are used instead. This option is toggled in the Verify Print dialog box. PageLaser If this is True, TG! will default to laser printers. Otherwise, TG! will default to dot-matrix printers. This option is toggled in the Verify Print dialog box. PageNumbers If this is True, page numbering will be active by default. Otherwise, page numbering will be disabled. This option is toggled in the Verify Print dialog box. InitialExtra If this is True, one additional extra line-feed will precede the article header information in print-outs. With some network print queues, the first page does not line up properly with subsequent pages; this extra line-feed is thus required for certain network print queues (like the servers in Oakland University's Kresge Library). If this is False, no additional extra line-feed characters will be sent. This option is toggled in the Verify Print dialog box. 6.4 Video mode, from the set [ COLOR | 43/50 | MONO ] VideoMode If this is Color, the standard color 80x25 screen is used. If this is 43/50, high-resolution color 80x43 or 80x50 (depending on if TG! detects EGA or VGA, respectively) is used. If this is Mono, the monochrome 80x25 display is used. This option is set in the "System" pull-down menu, available in Guide.EXE. 6.5 Printer port, from the set [ LPT1 | LPT2 | LPT3 ] PrinterPort This tells TG! what printer port to use by default. Note that any printer output can be redirected to COM (serial) ports by using the DOS MODE command. This option can be modified in the Verify Print dialog box. 6.6 Date pattern, from the set [ MM, DD, YY | YYYY ] DatePattern This tells TG! how to format the date output. Any combination of MM (for month), DD (for day), and either YY or YYYY (for year) is acceptable. The system will convert your text to upper case, so there is no difference between 'm' and 'M'. Any delimiters may be used to separate this information, except of course for 'm', 'd', and 'y'. Examples: MM/DD/YY United States (abbreviated) YYYY-MM-DD Canadian-French, Sweden DD-MM-YYYY Netherlands, Portugal DD.MM.YYYY France, Germany, Norway YYYYMMDD Undelimited Universal This pattern is specified in the Standard Options dialog box. 6.7 Output directory/path for ASCII files OutputPath This tells TG! where to output all ASCII files, both in the Guide.EXE "Save to ASCII" feature, and in Update.EXE's "Internal Article Editor." This should be a valid DOS path. For example, C:\GUIDE\ would tell TG! to save files into the Guide directory by default (which may be modified before anything is saved). This path is specified in the Standard Options dialog box. 6.8 Name of default GuideNET file GuideNETName This defines the default GuideNET file, used by both TG! and Update. Specifying a name here is the same as using the [ /LOAD=filename ] command-line parameter, and is modified in the Define GuideNET dialog box, available in Update.EXE. 6.9 Description of default GuideNET file GuideNETDesc This defines the default GuideNET description, used in the Update process. You may override this default on-screen before updating the data using the Define GuideNET dialog box, available in Update.EXE. 6.10 Input files, from the set [ RENAME | DELETE | PRESERVE ] InputFiles If this is Rename, Update.EXE will rename all processed *.NEW files to *.OLD when complete. If this is Delete, Update.EXE will delete the processed *.NEW files. If this is Preserve, Update.EXE will preserve the *.NEW files as *.NEW upon completion. This option may be set in the Update dialog box, available in Update.EXE. 6.11 Update options, from the set [ ACCEPT | IGNORE | UPDATE | MANUAL ] UpdOptions If this is Accept, Update.EXE will accept all articles in the *.NEW files, including duplicates. If this is Ignore, Update.EXE will ignore any duplicate articles found in the *.NEW files. If this is Update, Update.EXE will replace all articles currently in the system with duplicates found in the *.NEW files, if available. If this is Manual, you will have manual control over what articles are accepted from the *.NEW files. This option may be set in the Update dialog box, available in Update.EXE. 6.12 Update toggles, from the set [ TRUE | FALSE ] ApproveEach If this is True, you will be prompted with the filename of each *.NEW file. At this point, you may either select [ Ok ] to process the file, or [ Skip ] to ignore the file. Otherwise, all *.NEW files will be processed. This may be toggled in the Update dialog box, available in Update.EXE. MakeReadOnly If this is True, all GuideNET information will be marked Read-Only upon completion. Otherwise, no file attributes are modified. This may be toggled in the Update dialog box, available in Update.EXE. NoAutoUpdate If this is True, no automatic updating of replaced articles is performed. Otherwise, Update.EXE will replace old articles with new, updated versions when found in the *.NEW files. This may be toggled in the Update dialog box, available in Update.EXE. 7.0 The Guide! and Networks --------------------------- At the Parke-Davis plant in Rochester, Michigan, we use TG! as the on-line network help facility. Since TG! is basically a read-only system, use on a network is generally straightforward. However, some interesting problems can arise if the GuideNET information to be publically available is revised and updated frequently. It is due to these issues that TG!'s limited network support arose. If you do not use a network, or if your network GuideNET files do not require frequent updating (i.e., more than once a week), then TG!'s network features will probably not be necessary. 7.1 Background Information At Parke-Davis, instead of using the Adams-esque articles of Project Galactic-Guide, we use a series of custom-made computer support articles covering both hardware, software, policies, and how to contact the Plant Information Services for additional help. We call this custom GuideNET "PDInfo." A public batch file called "PDHELP" is used to access the TG! system. Our plant has three NetFrame 450's running Novell Netware 3.11. The TG! software is located in X:\DOSAPPS\GUIDE (where X: is a map to the PD1:APPS sub-directory), and the attributes are only read and file-scan for everyone (except me, as I require supervisory rights to update the files when necessary). I have a separate directory in my personal account where I create new articles and update the GuideNET. When a new GuideNET PDInfo is ready, I copy the PDINFO.* files over to the X:\DOSAPPS\GUIDE directory for public use. 7.2 The Interesting Problem This brings up an interesting problem. Let's say that a user is currently consulting the read-only GuideNET information, and the supervisor goes ahead and blasts in a new, updated set of data files. Chances are that during the exact few seconds it takes for them to copy over the files, the user(s) will not be accessing the disk (i.e., reading in a new article). Thus, Novell will not have any problems copying the new files over the old ones. Otherwise, Novell displays a standard error message, and the supervisor can wait a few minutes before trying again. Regardless, once new data files are installed, and if a user is still in TG! with the old article information (i.e., the titles, authors, indices, etc.) in memory, there could be a big problem. The next article that the user attempts to display will probably be "garbage" since the GuideNET data files on disk have changed, but not the information in the user's TG! memory (associated with these data files). 7.3 The Solution TG!'s limited network support attempts to resolve this. In the Guide.INI configuration file resides a variable called "NetworkSync." When this is set to True, network support is activated as follows: Associated with each GuideNET is a Synchronize file, created by the Update.EXE utility when the information is saved. This sync file is a way for TG! to know if the files on-disk have been changed "behind its back," so to speak. When TG! loads GuideNET information, it also reads this synchronize file into memory. Then, before TG! retrieves an article from disk, it always rechecks this sync file first, to see if the data has changed. If the sync file on disk is different than what it read before, then TG! knows that the files have been updated, so it reloads the current GuideNET with its new changes. Voila, problem solved. Almost. There still remains several "critical region" issues from standard Operating Systems theory. What if the user's TG! is trying to read the sync file while at the same time the supervisor is installing a new one? Why not use a file-locking technique by which the supervisor can detect when TG! is not in use, so updates can be performed absolutely safely? For the current situations, the above-described Synchronize technique does the job. However, as more network features are added, these additional issues may be addressed. 7.4 Network Testimonials (written by fellow TG! user Ronald Larsen, of the University of Oregon in Eugene, 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 (conveniently 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! | +--------------------------------------------------------------------------+ 8.0 Conclusions --------------- The Guide! was written with "Borland Pascal with Objects 7.0" using its 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 some bells and whistles, like SoundBlaster/AdLib support, or 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! Steve swbaker@vela.acs.oakland.edu "Gravity brings me down..." %e *EOA* * * End of GUIDE.NEW *