Universal Hint System Revision 91a Compiler for MS-DOS, Version 1.60 (January 7, 1993) Copyright 1992-1994 by Jason Strautman I assume that anyone who is about to write a file already has downloaded and used a 91a UHS reader, either for DOS or Windows. If you have not already done so, make sure that you do before writing any file, so that you can get an idea as to what the file should be like. You should also read a copy of the hint writing guidelines included in this ZIP archive for some helpful hints. Hunk Types ========== A 91a UHS file is composed of a series of various types of hunks. A hunk may either hold information, such as hints or author credits, or other hunks. Each hunk will contain a title which is shown in the readers for selection by the user. The hunk name may be abbreviated to 4 characters. Here are the types of hunks: [subject] --------- This may be the most important of the hunks in the UHS file, since it is used to group all of the other hunks, including other [subject] hunks. You will probably want to use several levels of [subject]s in the file, to help organize your file. There is no extra data in the [subject]; only a title and nested hints are used. [hint] ------ A hint may contain an unlimited number of ten-line clues. The title should pose either a problem ("I can't get through the door!") or a question ("How do I get through the door?"). The data that follows are the hints that answer the problem/question in the title. Each new hint should begin with the string ">> ", including the space. The hint should follow on the same line. If you need to use several lines in the hint, leave out that identifier, and only include the hint line in the data. [comment] and [credit] ---------------------- Both of these include a title and up to ten lines of data. [credit]s contain information about the author(s) of the file, while [comment]s cover anything else, except for game hints. [comment]s are often used to explain the file, such as how it is structured. See the guidelines for more information. [GIFa] ------ UHS 91a files may contain embedded GIF graphics, with a maximum resolution of 320x200, and no more than 16 colors. These graphics may be used to draw maps or point out an area on a screen shot. The data in the outline should be one line that has the path and filename of the GIF file. The proper data will be inserted into the compiled file. Additional hunks will be added by the compiler. However, you do not need to worry about writing these hunks yourself. The Outline =========== In order to create a compiled file, you will need to create an outline that gives the data which will be placed in the hunks. The first level of the outline is a single [subject] hunk, whose title is also the title of the game for which you are writing hints. This [subject] is automatically selected when the file is loaded. Every hunk after the [subject] should be indented two spaces. Indention tells the compiler that the hunks that follow are embedded in the previous [subject]. You should also indent an additional two spaces as more levels of hunks are used. All hunks that are on the same level will be indented the same amount of space. You should "un-indent" to separate hunks on the same level into different menus. Here is an example. (Any text in curly brackets is an added comment, that should not be included in the outline that you write.) [subject] Sample File {Notice that the title goes on the same line,} {with a space separating the two.} [subject] Grouping 1 (Item 1) [hint] Menu 1; Item 1 [hint] Menu 1; Item 2 [hint] Menu 1; Item 3 [subject] Grouping 2 (Item 2) {The indentation has changed. This means} {that the a new menu has been started.} [hint] Menu 2; Item 1 [hint] Menu 2; Item 2 [hint] Menu 2; Item 3 [subject] Grouping 3 (Item 4 on Menu 2) [comment] Menu 3; Item 1 [hint] Menu 3; Item 2 [hint] Menu 3; Item 3 [subject] Grouping 4 (Item 3) {This is on the same level as groupings 1} {and 2, since is indented the same amount.} The top menu of the file contains three choices: "Grouping 1", "Grouping 2", and "Grouping 3". If the user selects "Grouping 1", then three choices will be presented. "Grouping 2" is outdented from the three hints above it, so the compiler knows that item 3 is the last one on the first menu. But since this grouping is aligned with the first one (and nothing is outdented between the two groupings), both are found on the same menu. The second grouping has four items, including one additional grouping. Notice that all are on the same level of indentation. But "Grouping 3" provides even further structuring on the file, which contains three additional choices. "Grouping 4" is to the left of both "Grouping 3" and "Menu 3; Item 3". Both groupings 2 and 3 are ended, since this [subject] is outdented from the items under the previous two subject. But once again, the [subject] is on the same level as the first two, so all are on the same menu. The data of a hunk is also indented two spaces from its title line. But with the exception of the [subject] hunk, no additional hunks may be added inside another. A [comment] hunk would be written as follows: [comment] Things to Know This is a properly written file, or at least a portion of one. In a real file, there would be a [subject] above this, and this hunk would be indented, since it is a part of that main [subject]. [hint] But this hunk is illegal. >> It should be on the same level as the *title* of the [comment], as found in the next [hint]. [hint] Now this is correct. >> Notice how the title is aligned with the title of the [comment], since both should be on the same level of the file. >> If you didn't want these two hunks to appear on the same menu, you would have to use a [subject] to separate them. In your outline, you may use blank lines for clarity. You can also use semicolons (";") to mark comments that will not be included in the compiled file. The semicolons should be in the first column of the line, not indented. IMPORTANT NOTE: The 78-character limit mentioned in the guidelines does not include any indentation, the type of hunk included in square brackets, or the ">> " of a new line of hints. Begin your count with the first character of the title or data. So a line like " >> Test" counts only for four characters, not the 11 that you would count by looking at the column number in the editor. Try to use close to the full 78 characters per line -- with the editor, it's easy to do this, since the line length shown is also 78 characters. Just try to put as much text on one line as you can see without having any of it wrap off the screen. Sample Outline ============== This is a short version of how a UHS outline should be written, and of how the file might be structured. I have used the four-character abbreviations for the hunk names. And in case you are printing this text file out, I have cut off lines longer than 80 characters, even though you can use longer lines in the outlines. Just make sure that the data is shorter than 78 characters. [subj] UHS 91a Sample File ; The following block is the first selection on the "main menu" [subj] General Information [comm] Everything you wanted to know about the UHS, but were afraid to ask: The Universal Hint System was invented by Jason Strautman (CIS [72337,261 AOL JStrautman). [cred] About the file author. Jason (we've seen his name a lot on this file, haven't we?) Strautman wrote this file. He can be reached on CompuServe at [72337,2611], or on AOL as JStrautman. [cred] About SAMPLE's publisher. If SAMPLE were a real game, then you might see the game's publisher, designer, programmers, or other related people mentioned here. But since SAMPLE doesn't exist, then you won't see anything here. [comm] Writing your own UHS file I'm not going to go through that long speech, since it's in this manual. ; Second selection [subj] The Mountains [hint] How do I get past the small giant? >> First of all, you should ask yourself what a small giant is. >> The phrase "small giant" is an oxymoron. An oxymoron is a phrase that contradicts itself. >> Now think about whether or not an oxymoron can exist in reality. >> If you're literal enough, they can't exist. >> You'll have to figure out how to be literal with the parser. >> Just think away the small giant, and he'll disappear. The only thing left is an explanation of the interface. Read your manual to find out how to do so, and the giant should disappear. [hint] How do I climb down the cliff? >> Do you have anything like a rope in your inventory? >> Of course you don't. That would be too simple of a puzzle. Do you see any formations on the rocks? >> And have you ever seen mountain climbers? They use spikes for their work. >> So you can use an icicle. Break off an icicle with your hands and use it on the cliff. ; Use further nesting to handle multiple solutions, if you want ; All of the details are hidden away on a new menu [subj] How do I get enough money to pay the guide? [comm] What is the difference in the two solutions? The first one requires you to be violent, but it gets you more points. The non-violent (second) solution gets you fewer points, although it does make for better family entertainment. [hint] Solution I >> If you read the comment above, you would realize that this is a violent solution. >> The banker is probably carrying money in his briefcase. >> He's also probably unarmed. >> Just shoot him and steal the money. [hint] Solution II >> This is a non-violent solution, but it's still not "nice." >> I guess you've been to the alley. >> Then you must have seen that bum. >> He's blind. >> Just steal the money from his hat. ; Third selection [subj] The Valley [hint] Why is the valley so empty? >> Do you see anything interesting to do here? >> Of course not! >> That's why the valley is so empty - it's too boring. [hint] I've fallen and I can't get up! >> Did you buy Life Savers? >> They wouldn't do you any good anyway, since you don't need candy. >> You still should have chosen a similarly-named product. >> Remember the Life Saver II? Restore and buy it instead. ; Fourth selection [subj] Maps [gifa] The Mountains: Part I C:\MYUHS\MOUNT1.GIF [gifa] The Mountains: Part II C:\MYUHS\MOUNT2.GIF [gifa] The Valley: Part I C:\MYUHS\VALLEY.GIF The Editor ========== This is pretty much a standard text editor that uses standard text editing keys. You can leave multiple files open at the same time, and even though the default filename is "*.91A", you can open any file of any type, either from the menu bar or by entering the filename as a command line parameter. Files must be smaller than 64K. If you are working on a UHS outline, the editor will make its best guess about what type of data you will want to enter next. It will assume that a "[hint]" follows each "[subject]", a ">> " follows each "[hint]" or another ">> " and an unformatted line follows any other kind of hunk. The editor also auto-indents your data as necessary, but it does not wrap your text to the next line. If you don't like the formatting that the editor suggests, you can override it in several ways. The first of these is to press CTRL-ENTER instead of ENTER at the end of the line; when you do this, the editor does not insert any hunk types on the next line. A number of function keys are also provided to change the hunk type that the compiler gives you. Be careful using these, though, because any text to the left of the cursor will be deleted. You can also use the CTRL-B key combination to quickly wipe out the line and unindent 2 spaces. Press the F1 key for more information on what these keys are. Running the Compiler ==================== Once you've created your outline, you need to get authorization from me to use the compiler. Send me an e-mail message or write to me through the post office. Addresses are listed at the bottom of this document. Let me know the game that you want to write hints for, and give me the file title *exactly* as it will appear in your file. I will send you a code that is based on this title, so if you change the title, then the code will be invalid. If someone is already working on or has finished a file for this game, I will let you know, so that you can select another game. And once you are finished, I will send you a registered copy of the DOS, TSR, and Windows readers on a disk. You will need to enter the information needed to compile your file from within the editing environment. Select "Compiler | Parameters" and enter the appropriate filenames into the dialog box. These parameters will only affect the file that you are editing at the time you open the dialog box. If you wish to make changes to the parameters for other files, you must first open those file(s), select their edit window, and then select "Parameters" from the menu bar. The compiler will assume that every file is located in the current directory; if a file is not in that directory, you will need to specify the drive and/or path name. The input file is the outline you are working on, the output is a completed .UHS file, and the 88a header is a UHS 88a file that will be displayed on 88a-only UHS readers. You should use the STD_88a.UHS file or some other UHS 88a file that instructs people on how to find a newer UHS reader so they can view your hints. The authorization code is the number that I will give you. Note that I may not give you an authorization code when you first volunteer to write a file. I will put you down as the author for that particular file, but I may require a sample of your work before I give you a permanent code. While you are waiting for your code, you can enter the word "TEST" in place of the code in the parameter dialog box. The title of the file will be changed and each line truncated, so that your file cannot be distributed, but you will be able to clear all errors and get a general sense of how your file will look. You only need to enter this information once per file; it is saved into a file called UHSCMP.INI and will be loaded whenever you start the compiler. The UHSCMP.INI file should be in the same directory as the compiler. You can create or edit this file if you want to change the parameters without using the dialog box (perhaps in a batch file). Each line in UHSCMP.INI specifies the information in the dialog box, in the same order as shown there. The parameters for compiling multiple files can be stored in UHSCMP.INI; each file's parameters are stored in consecutive blocks of 4 lines each. If you edit this file yourself, do not store any additional blank lines or comments. Once you have specified the necessary information, select "Compiler | Compile" from the menu bar to create a .UHS file from the outline that you are currently working on. The appropriate set of parameters for the current file will be loaded from the UHSCMP.INI if you have entered them; if no parameters have been specified, the compiler will tell you this and demand that you enter parameters before compilation begins. You will then be informed on the progress of compilation. Any errors will also be reported as they are found. If there are any errors detected during compilation, they will be listed again after all portions of the file have been checked. Otherwise, the file will be closed, ready for testing and distribution. Errors ====== Here is a list of all the possible errors in a file: #1) Multiple titles were detected within the file. You should have one [subject] in the first column, and all other hunks should be indented within that title hunk. If you have to, create a new title and place your other [subject]s inside that hunk. #2) (this error will never be displayed) #3) You specified a hunk that was not one of the ones listed above. Check your spelling on that line. #4) You created a [credit] or [comment] that is longer than 10 lines, the maximum for a 91a files. You should change the hunk into a [hint] hunk, with several (multi-line) hints, or break it into several [credit] or [comment] hunks. You might also want to consider shortening your text, since you should rarely need more than the given space. #5) You indented something other than a hunk inside another hunk. A hunk name should begin with a left square bracket ("["). You may have simply forgotten to add the bracket before the hunk type. You cannot indent data text, even for visual effect; the compiler believes that this is a new non-hunk hunk. If this is the case, start the text on the same column as the rest of the data. Or, move the semicolon of a comment to the first column. #6) A [GIFa] hunk should only have one line of data: the filename of the external GIF file to be important. Make sure that you start a new hunk on the line after that oneline of data. #7) You attempted to place another hunk inside a [comment] or [credit]. Remove it, or bring it to the left to place it on the same level as the [comment] or [credit]. #8) The same as #7, only with a "parent" [hint] hunk. #9) A character not in the range of ASCII codes between 32 and 127 was detected. Do not include accent characters for foreign languages, which may cause this problem. Also make sure that no word processing commands are in your outline. #10) Your line is over 78 characters. If you can break it into two (if it is part of the data set for a [comment], [credit], or [hint]), then do so. If it is the title to a hunk, you must shorten the title. One additional error will cause the compiler to stop: an invalid authorization code. The entire file will be checked, so that you can continue to correct any errors while you are waiting for the authorization code. But you will not have a completed file to distribute. If you do have a code, check to make sure that the title you sent me matches the title in the outline. Distribution ============ This compiler may be used without any cost. However, distribution is limited to non-commercial BBS's, provided that this archive is not modified, that no fee is charged for access to the UHS and its related files, and that the BBS is open to the general public. But please send me a letter letting me know when the UHS has been uploaded. Anyone else wishing to distribute the UHS must receive prior approval from me. Changes Since Version 1.00 ========================== 1.60: Offers better support for editing multiple files at one time (UHSCMP.INI can hold multiple parameter entries). The compiler automatically detects and compiles the file in the current window, and not just whatever file is listed in UHSCMP.INI. Errors are logged to a separate file for easy review, and all messages printed during compilation are shown on the same screen as the editor, rather than on a separate screen. ".91a" is assumed as the default extension if none is specified at the command line. Allows a test file to be generated without proper authorization code. Adds the "External" option for compiling files that are not contained in an editor window. 1.51: Corrects errors that sometimes appeared at the end of the file if the outline contained too many blank lines. 1.50: Adds integrated editing environment and makes related changes. 1.02: Allows comments to be placed inside [hint]s and [comment]s. 1.01: Mentions America On-Line in compiler author information. Jason Strautman 239 Redwood San Antonio, TX 78209 CIS: [72337,2611] AOL: JStrautman