The Silicon Frog, Inc. John Hancock 3.0 The JH3MAINT Program Version 1.0 (c) 1988-92 The Silicon Frog, Inc. All Rights Reserved Table of Contents Introduction...............................................1 Installation...............................................1 Starting JH3MAINT..........................................2 The JH3MAINT File Selection Screen.........................2 Quitting JH3MAINT..........................................3 Principles of Operation....................................3 The File Maintenance screen................................3 The Status Line........................................3 Marking / UnMarking taglines...........................3 JH3MAINT Commands..........................................4 File Commands..............................................4 <1>/<2>, / - load 1 and load 2.................4 / - vieW 1<>2 .................................5 - New file.........................................5 / - saVefile...................................5 - deLfile..........................................6 - chgTitle.........................................6 - scrnsiZe.........................................8 <1..F> - Screen Colors............................8 Tagline Functions..........................................8 - Edittag..........................................8 - Findtag..........................................8 , - Insrttag...................................9 - Copytag..........................................9 , - Deltag...................................10 - Movetag.........................................11 - mrKall..........................................11 - Unmrkall........................................11 - invmaRks........................................12 - stdsOrt.........................................12 - Smrtsort........................................12 Quitting JH3MAINT.........................................13 A Sample JH3MAINT Session.................................13 That's All, Folks!........................................14 JH3Maint Page 1 Introduction JH3MAINT is the JH3 tagfile and tagline maintenance program. This wonderful, sophisticated, state-of-the-art tool lets you organize, create, delete, sort, copy, and otherwise mangle, fold, spindle, and mutilate tagfiles. If your tagfiles are completely out of whack, JH3MAINT is for you. If your tagfiles are perfectly organized, JH3MAINT will help you correct the problem ("An organized tagfile is the sign of a sick mind"). JH3MAINT is quick, easy to use, and 100% mouse-friendly. If you have no mouse or if you hate rodents, or if you have a mouse and you don't like it, JH3 will also let you use the keyboard, a feature which we at the Silicon Frog felt was necessary. Recalling your experience with JH3CFG, remember that if you do have a mouse and don't like it, unplug it. JH3 is good, but it still can't quite read your mind. Software extrasensory perception will be a feature in JH4. OK, let's get serious. JH3MAINT will help you: - Create new tagfiles - Delete tagfiles - Change tagfile titles - Add taglines to tagfiles - Delete taglines from tagfiles - Copy taglines between tagfiles - Move taglines between tagfiles - Sort tagfiles - Do all sorts of wild and wonderful things, most of them legal. Installation JH3MAINT needs no special installation procedures. For JH3MAINT to operate, the JH3 environment variable must be set properly and the JH30.CFG file must point to your tagfile directory. If you type 'JH3MAINT' at the DOS prompt and DOS tells you "Invalid command or file not found" then you didn't copy JH3MAINT.EXE to your JH3 directory, you're not in your JH3 directory, or your JH3 directory is not in your DOS PATH. For additional information about directories, DOS, the DOS PATH, and the JH3 environment variable see INSTALL.DOC. If you followed the directions in INSTALL.DOC, you shouldn't have any problems. If you don't like to read documentation, file a grievance with your Software User Union Representative or write a letter to your senator. Just JH3Maint Page 2 don't call me in the middle of the night. Thank you. Just remember: JH3 installation procedures have been thoroughly tested by a lot of people with only half your brains. You have no excuse. Another definite prerequisite to running JH3MAINT successfully is that all your .tagfiles have a standard title. See INSTALL.TXT for additional details. Starting JH3MAINT Go to your JH3 directory, type JH3MAINT at the DOS prompt, and press . That's it. No command-line parameters. The JH3MAINT File Selection Screen When you start JH3MAINT, the program displays its file selection screen. From top to bottom, the file screen consists of: 1. The title line, which contains the program's name and *your* name (only if you're registered. If you're not, send me money and we'll fix you right up), 2. A file selection window, which works the same way as JH3's tagline selection window, and, 3. A file status line, which is mostly blank since you haven't loaded a file yet. More on the status line later. The first entry in the file selection window is always [New File]. You should select this entry if you wish to create a new tagfile at this time. If you do, JH3MAINT will prompt you for the 1- to 8-character tagfile name (the .TAG file extension is assumed and need not be typed). If you use an existing file name, JH3MAINT will tell you about that too. For your convenience, the [New File] function can also be invoked from the file maintenance screen. If you select the [New File] option, JH3MAINT will create the file immediately; it will contain a single tagline and will have a default title showing the file's name and creation date and time. Of course, the new file's title will be displayed in the selection window so that you may select it (JH3MAINT does not load new files automatically). The file selection window contains the available .TAG files' titles. As explained in INSTALL.TXT, the "title" is the first line of a tagfile. In order to ease file selection, title lines contain a user-defined hot letter, which can be used to select the file with a single keystroke. JH3Maint Page 3 To select an existing file, press its hot letter, or cursor to it and , or doubleclick on its file name. Quitting JH3MAINT To terminate JH3MAINT, press , click the outside mouse button, click on the Quit button, or press . Principles of Operation JH3MAINT can load two tagfiles in memory at the same time, which allows very fast copying and moving of taglines between files. Both files are not on the screen at the same time; you must switch the display from one file to the other manually. Files are referred to by their number; the first file loaded by JH3MAINT is always #1. From then on, you always get to decide which file will be loaded - JH3MAINT will prompt you to save a file that was changed before loading another. Press to save the changes or to obliterate them. The File Maintenance screen Once you have picked a tagfile from the file selection screen, JH3MAINT loads it into memory and switches the display to the file maintenance screen. From top to bottom, this screen contains: 1. The same title line, 2. The main screen area with command buttons on the left and the tagfile window on the right, and 3. The file status line at the bottom of the screen. The Status Line The file status line shows which of the two tagfiles is displayed in the main screen area (if you have two files loaded), the number of taglines in that file, and how many taglines are marked. Marking / UnMarking taglines JH3MAINT makes no assumptions as to which taglines you wish to copy, move, or delete; program functions which alter the contents of tagfiles require that you first 'mark' at least one tagline. When you mark a tagline, a small square JH3Maint Page 4 appears to its left. There are a number of ways to mark or un-mark taglines: 1. With the window cursor on the desired tagline, press or the <+> key. This will toggle the mark for that tagline ON or OFF and advance the cursor to the next tagline. Pressing will toggle the mark, but will not advance the cursor. Pressing forces the mark on in the event you're marking an entire range and one or more of the taglines are already marked. 2. Pressing or <-> will toggle the mark and will move the cursor to the previous tagline. Pressing will force the marks ON. 3. If you have a mouse, doubleclicking on a tagline will toggle its mark and advance the cursor (the same as pressing ). 3. As their names indicate, the marKall and Unmrkall commands can be used to mark or un-mark the entire file. Remember: if you plan to copy, move, or delete taglines, YOU HAVE TO MARK THE SUCKERS FIRST. If you do NOT, JH3MAINT will question your mental abilities, ancestry, willingness to read .DOCs, or all of the above. JH3MAINT Commands To issue a command, press the highlighted character in the command button's legend, or click on the desired command button. To confirm the command, JH3MAINT will visually press the button for you. Commands are arranged in three groups: 1. File and display functions 2. Tagline functions (and the Quit command) 3. None of the above File Commands <1>/<2>, / - load 1 and load 2 The <1>/<2> or / commands will load a tagfile into the first or second file window. When you start JH3MAINT, the first file you select is loaded into the first file window by default; the program automatically issues a "load JH3Maint Page 5 1" command whenever it is started. If a file is already loaded in the window, and it has been changed, JH3MAINT will prompt you to save it. To reply to the File Save prompt, press or , or click on the letter Y or N in the prompt itself - the mouse cursor will be positioned on the default reply (Y). I told you this was a sophisticated program, no? If you want to copy or move tags between files, both files must be loaded in memory. Use the load 1 and/or load 2 command to make sure that both source and destination files are available to JH3MAINT. JH3MAINT will not let you load the same file twice. Whaddya *mean*, ya don't believe me? Just go ahead and try it. Make my day. The top line of the file window shows the file number and its title. For example: 1-My favorite Mark Twain Taglines / - vieW 1<>2 Use the command or press to switch tagfile displays. Of course, JH3MAINT will question your wisdom, in writing, if you try to switch file displays when only one file is loaded. Remember: the tagfile you're looking at is always the "source" file for copy or move commands. - New file The command is equivalent to selecting the [New File] entry in the file selection window. JH3MAINT will prompt you for the new file's name (no .TAG extension, please), and the file will be created. You may not create a file which already exists or even overwrite it, since it may contain precious taglines, and if this was allowed I'd never hear the end of it. If you want to re-use a file name, delete the original file first, or load the file and delete all of its taglines. / - saVefile The or command will save the displayed file. When saving (or deleting) a file, JH3MAINT always creates a backup of the original with a .BAG extension. To restore the original file, you should delete the new file (manually JH3Maint Page 6 from the DOS prompt or with the deLfile command), then manually rename the ????????.BAG file to its original ????????.TAG extension. - deLfile The command will delete the displayed file. Of course, JH3MAINT, being a mild-mannered program, will first ask your permission; deleting tagfiles without permission is not nice. Perceptive readers will ask "Hey! Bozo! How can you delete something I'm looking at?". This is an excellent question. The hard part is NOT deleting the file you're looking at; it's deciding what to do *afterwards* (e.g., have a smoke, a drink, or raid the refrigerator). Here's the official scoop: - If you delete the only file that's loaded, JH3MAINT will return you to the File Selection screen. Since there are no files to look at, it's either that or terminate the program - an unsafe assumption. We did think about implementing this assumption for unregistered users, however. - If two files are loaded, and you delete one of them, JH3MAINT will automatically switch the display to the remaining file, the only viable option. - chgTitle The command allows you to edit the file's title, displayed on the top line of the file window. File titles *must* contain a hot letter or character - this character is highlighted in the file selection screen and can be used to select the file with a single keystroke. By definition, the hot letter is preceded by a percent sign (%). For example: My Favorite %JH Taglines (hot key = "J") Really stupid %Hardware taglines (hot key = "H") Glenn's real stoopi%d tags (hot key = "D") Although you may assign the same character twice, DON'T DO IT!!! JH3MAINT and JH3 will always select the first file whose hot character matches the key you pressed; if there are duplicates they must be selected manually with the cursor keys or the mouse. Note that the hot key does NOT have to be the first letter of a word. The same single-line text editor is used in all JH3 programs. The following editing keys are available: JH3Maint Page 7 Key Action ------------- -------------------------------------- move 1 character to the right move 1 character to the left move to beginning of next word move to beginning of previous word move to start of text move to end of text restore original text clear text delete character at cursor delete previous character toggle insert/overstrike mode accept edit cancel edit and, of course, for you rodent aficionados: Mouse Action ---------------------- ---------------------------- Click inside text position cursor Click outside text accept edit Click outside button cancel edit Note that the same editor is used for all text input and edit functions: taglines, file names etc... The editor clears the input field if you type a significant character first when the cursor is at the beginning of the text field - JH3MAINT assumes that you wish to re-type the entire field. To disable this feature, press a cursor key *first*. For example, press , which has no visible effect when the cursor is already at the beginning of the field. Note that when you edit the tagfile title, the % hot key prefix is shown in its rightful location (the prefix is not shown when you do anything else). If you remove this character, JH3MAINT will gently remind you that YOU MUST HAVE THE % CHARACTER SOMEWHERE IN THE TITLE, DARNIT! JH3Maint Page 8 - scrnsiZe The command cycles thru available screen sizes on EGA or VGA displays. JH3MAINT fully supports Personics' UltraVision(tm) (a.k.a. "UV") display enhancement software. The following screen sizes are available: EGA: 25 and 43 lines VGA: 25, 28, 43, and 50 lines UV/EGA: 25, 34, 43, and 60 lines UV/VGA: 25, 36, 50, and 63 lines By default, JH3MAINT always starts with the same screen size as JH3. After all, if you picked that screen size, you must like it, no? Pressing or clicking on the screensiZe button cycles through all available screen sizes for your video type. Feel free to try on an original monochrome (MDA) or CGA displays. If it *does* work, something is definitely broken ( should work on monochrome E/VGA displays). <1..F> - Screen Colors JH3MAINT may use any of the 16 customized colorsets defined in JH3CFG's Crayola Box (tm). To select a different colorset, use the <1> through <0> (sets 1-10) and through (sets 11-16) commands. The new colorset will be JH3MAINT's default until you change it again. Tagline Functions - Edittag The command allows to edit the highlighted tagline. It works the same way as the chgTitle command, so go back a few paragraphs if you want to find out more about it. You may type extended ASCII characters by pressing the key, holding it down, and typing the desired character's ASCII value on the numeric pad. - Findtag Unlike JH3's command, which displays all matching taglines in a single window, JH3MAINT's command repositions the display to the first tagline that matches the search JH3Maint Page 9 argument. To find the *next* matching tagline, use , or press the while clicking on the Findtag button. If JH3MAINT can't find any matches, it will tell you. The Findtag command observes the WordSearch setting defined in JH3CFG's Preflite Checklist. See JH3CFG.DOC for additional details on this wonderful feature. , - Insrttag The command inserts a new tagline in front of the current one. When the command is issued, the display shifts downward below the insertion point, and the tagline editor receives control. Editing rules are the same as for the title editor described earlier, with one notable difference: if you cancel the editing, the new tagline is removed and the tagfile is restored to its original status. - Copytag The command copies all marked taglines from the current file - the one you're currently viewing - to the second file loaded in memory. Needless to say, you MUST have another file available to which the marked taglines will be copied. As mentioned earlier, the "source" file is, by default, the file that is currently displayed, and the "destination" file is the one that's not. You have total control over the location to which taglines are copied - it is not selected at random: - If you loaded the destination file, and NEVER moved the window cursor, copied tags will be added at the end of the file. - If you moved the destination file window cursor away from its original, top-of-file position, copied taglines will be inserted at the cursor location. When you switch ( or ) to the destination file after a copy or move operation, the display is automatically repositioned to the copied tags, just to show you Doubting Thomases that the copy operation worked OK. I mean, if you can't _see_ them copied tags, how do you know they're there, huh? Note that copied tags retain their marks for easy identification. And easy deletion in the event you copied them by mistake. You may note the change in the status line JH3Maint Page 10 when copying tags: the marked tag count in the destination file increases by the number of copied taglines. Of course, copied tags remain in the source file, complete with their marks. A Copytag command may fail if there is not enough room in the destination file. This is unlikely to happen unless you are dealing with very large tagfiles. Memory is not a problem, since JH3MAINT will not operate unless there is sufficient DOS memory available to load two maximum-size tagfiles. The most common use for the Copy command is Tagfile Reorganization. After a while, your tagfiles can become rather messy and disorganized. Most people group taglines by topic, but they usually don't start that way. Also, you may want to copy your best taglines to FAVORITE.TAG, and enter it into the Great Semi-Annual Silicon Frog Taglines Contest. The G.S.F.T. contest may be entered by Registered Users only and features fantastic prizes. Contest rules and details are included on the bonus disk you receive when you register. , - Deltag The command deletes marked taglines. For safety's sake, and to insure my continued physical well-being, JH3MAINT issues a confirmation prompt before deleting taglines. (remember, your original tagfile will be saved with a .BAG extension in case you answer Y to the prompt when you really meant N). You may delete ALL the taglines in the file, but JH3 cannot operate with empty tagfiles, so a single default tag will remain in the file. If you want to delete the file, do NOT delete all its taglines; use the deLfile command instead. Deleting all tags may be useful in the case of the STOLEN.TAG file, which is the official stash for the tagloot appropriated by totally unprincipled programs such as RobbinHS, Guido, and PierreHS, a.k.a. "The New Thieves", which you receive when you register JH3. For example, use the Copytag command to distribute stolen taglines to other, permanent tagfiles, then mark all the taglines in STOLEN.TAG and delete them - you're now ready for another round of Happy Burglotagging (tm). JH3Maint Page 11 - Movetag The command moves tags to the destination file - it copies them to the destination file, then deletes them from the source file. Since the taglines are not physically lost, this command does not require a confirmation prompt - but it does issue a confirmation message. The location of the moved taglines is the same as if they had been copied (see the Copytag command for additional details). The status line reflects the move by decreasing the source and increasing the destination tagline & mark counts by the same amount. But what if you really did not mean to move the *$@*)! taglines? Well, the hardest part of the recovery is admitting to yourself that you're imperfect. The recovery itself is trivial: switch the display to the destination file and issue the Move command again - the taglines will be right back where they came from as if the original move never happened. Yes, folks, this is Yet Another Great Silicon Frog "Don't Let Them Step On Their Own Toes" feature. - mrKall The command unconditionally marks all the taglines in the current file. After a command, the status line's tag and marked counts will be the same. If they are not, WHACK the top of your computer a couple times; it has to be a hardware problem; the software itself was compiled with the "NoProgramBugs=True" option and is perfect. If this does not correct the problem, buy a new computer. The command is very useful when you wish to mark all or even *most* of the taglines in a file in preparation for copying, moving, or deletion. If you want to mark 90 of 100 taglines, it's much faster to mark all 100 of them and unmark 10 of them than to manually mark 90 of them (although I know some folks who will always use the latter method). - Unmrkall The command unconditionally unmarks all the taglines in the current file. Its main purpose is to allow you to quickly recover from having pressed by mistake, or remove the marks from taglines that are widely scattered all over the file. When you issue the command, the status line's mark count immediately drops to zero. If it does JH3Maint Page 12 not, immediately follow the computer recovery procedures outlined earlier under the mrkAll command. - invmaRks The command inverts marks: marked taglines are unmarked, and vice-versa. Why would you ever want to invert marks? Excellent question. I actually found a *real* use for this command. Suppose that you want to split a tagfile into two new ones. Load the original tagfile, create the two new files, and load one of them. Mark the tags to be copied, and move them. Now load the second new file, invert the marks, and copy the remaining tags to it. Voil! - stdsOrt The command will sort the entire tagfile in standard ASCII collating sequence. If all of the taglines in a file start with upper or lower-case letters or numbers, this sort is extremely fast. However, the ASCII alphabet is NOT a "standard" alphanumeric sequence - ASCII characters are sorted as follows: 1. Control characters (e.g., Smiley , arrowheads , card suits ) 2. Punctuation marks and some special characters (! " $ %) 3. Digits 4. More special characters (= < > : ;) 5. UPPER-CASE letters (ABC) 6. More special characters ([] ^_) 7. Lower-case letters (abc) 8. More special characters ({} ~ |) 9. International, currency, fractions ( ) 10. Character graphics ( ) 11. Scientific symbols/Greek ( ) If your taglines start with spaces or special characters, the command will yield interesting results. It's worth a try. - Smrtsort The command performs a "Smart Sort", which disregards all leading non-alpha characters and uses a true alphabetical sequence (lower-case and UPPER-CASE) are sorted JH3Maint Page 13 together. This sort is slower than the standard sort, since it must first normalize each tagline before sorting. Both sorts preserve marks. Quitting JH3MAINT To quit JH3MAINT and return to DOS, press or click on the Quit button. If tagfiles were changed, JH3MAINT will prompt you to save them. ONE MORE TIME: JH3MAINT backs up original files with a .BAG extension, so your original files are protected. A Sample JH3MAINT Session Case: you have an enormous JH.TAG file which you want to split into smaller ones. Here's how to do it: 1. Decide how you will organize your taglines. The most common method is by category. For example, All-Time Favorites, Political, Computer Hardware, Real Silly, etc... 2. Start JH3MAINT. Use the opening file selection screen's [New File] option to create as many files as needed. Assign them meaningful names, such as FAVORITE, POLITICS, SILLY, HARDWARE, etc... 3. Select the JH.TAG file (or whatever your huge file is). It will be loaded into file window #1, and the file/tag maintenance screen will be displayed. 4. Use the <2> command to load the first of the new files, for example, FAVORITE. 5. Now comes the hard part: manually mark the taglines in JH.TAG which you want to move to the FAVORITE.TAG file. If your tags aren't organized in any order, this may take a while. 6. Once the tags are marked, use the Movetag () command to move the tags to the FAVORITE file. 7. Use or press to switch the display to the FAVORITE tagfile. 8. Optionally delete the first tag which was added to the file when it was created. JH3Maint Page 14 9. Use the chgTitle () command to change the FAVORITE file's title. Remember to define the hot key; in the following example the hot key is F: My %Favorite JH Taglines 10. Optionally, sort the new file with the or command. 11. Use the <2> command to load the next new file in the second file window. Reply when JH3MAINT asks you if you want to save FAVORITE.TAG. 12. Use the or command to return to the JH.TAG file. 13. Repeat steps 5 through 12 until done. During the process, you may very well come up with ideas for new categories. If you do, use the Newfile () command to create the new files as needed. That's All, Folks! JH3MAINT is far more sophisticated than its release 2.0 ancestor - with JH3MAINT, you should be able to keep your tagfiles in top shape and able to pass Mom's white glove test. One recommendation: don't let your tagfiles grow to unreasonably large sizes; use JH3MAINT to split them into smaller files. Once a tagfile reaches 400 or 500 taglines, it becomes more difficult to navigate, and it takes longer to load. Then again, JH3 and JH3MAINT will let you build very large tagfiles if that's what you like. My recommendation: organize your tagfiles by category. Also, remember to use meaningful tagfile titles -- that's what shows up in your tagfile selection window. With JH3, tagfile names are not nearly as important as they were with JH2. Of course, if you enjoy JH3MAINT and other JH3 programs, consider registering. Thank you for your support and Happy tagging!