Universal Hint System
Revision 91a
Hint Writer's Guidelines
  (June 3, 1993)

Copyright 1992-1993 by Jason Strautman.
To be distributed with all UHS compilers.

 
Introduction
============
 
First, I would like to thank you for taking the time to write a UHS file.
But before you begin, you should always contact me, in case someone else is
already writing a file for a given game.  I am available on CIS
([72337,2611]) or AOL (JStrautman).  In case you cannot reach me on-line
for any reasons, you may also contact Bob Norton on CIS at [70017,1765].
 
Whenever you write a UHS file, you should follow the guidelines that I have
listed.  By contacting me or uploading your file to CIS or AOL, you are
also giving me (or anyone else whom I might designate) permission to edit or
distribute any files for non-profit purposes (i.e. uploading them to other
bulletin boards or on-line services or to give them to registered users).  But
I will not sell any files without prior permission from you.  If you do not
wish your file to be distributed, please send me electronic mail and include a
notice in your file.  Please do not offer your individual files as shareware.
Other than the above restrictions, there should be no obligations associated
with any 91a compilers.  But check the documentation, just in case.
 
 
Guidelines
==========
 
(These are in no particular order, by the way.)

 1. In any case, you should not use binary (those with ASCII values higher
than 127 or lower than 32) characters in your files, regardless of computer
format or intended audience for your files.  The UHS compiler will remove all
such characters.  (If you do not know which characters are binary, it is
usually safe to enter any character that does not require holding CONTROL or
ALTERNATE.)
 
 2. No line should contain any more than 78 characters of text, regardless
of the line's purpose (excluding the CR/LF at the end of each line.)
Additional text will be truncated, or the source may be rejected until long
lines are shortened.
 
 3. When giving hints, use the [hint] option in the file.  (See your
compiler's documentation to see how to create each hunk type.)  Do not use a
[comment] section, since it will not provide options for step-by-step hints.
Your hints should provide clues starting with gentle nudges and ending with
an exact solution.  If it impossible to give any hints, then give a warning
in the previous hint stating that the next hint will be a direct answer.  You
usually do not have to warn people when the solution is coming if you have
provided the proper sequence of nudges.  Also, you should only use multi-line
hints where they are necessary (when a particular hint is longer than 78
characters).  If a hint can be broken into two distinct hints, do so.  For
examples on how to provide nudges, look at any UHS file written by Bob
Norton, CIS [70017,1765], or by Jason Strautman, CIS [l2337,2611] or AOL
JStrautman.  Select a file for a game that you have played, so that you can
understand the hints fully, and so that you do not spoil another game that
you may later decide to play.
 
 4. Your question (or phrase) that will be selected by the user should not
give any more information than is needed to present the problem. In other
words, you should not provide a question such as, "I've just killed the
trolls with the magic sword and stolen the gold from their backpacks. But
after I go past the mauve doorway, I am killed."  The proper question here
would be "How do I keep from being killed after passing the mauve doorway?"
In this example, if stealing gold causes you to be killed, then state this
in the hints, not in the question.  Also, do not pose questions that assume
the user knows what is going on.  For example, "I can't get the dwarf to
jump on the knife!" should not be used over a simpler "How do I get rid of
the dwarf?" question.  If questions that give away solutions are inevitable,
make sure to include a few fake hints so that reading questions alone will
not be enough to provide information.
 
 5. Take advantage of the [subject] option to group questions, comments,
credits, and GIF maps.  You should usually start out with one level that
includes nothing but [subject]s.  (Users of the older UHS 88a files will
remember this as the topic level.)  I usually have "topics" for different
geographical areas of the games, although at times, you might have to
group the game by the progression of time (such as an "endgame" category).
You may also use nested [subject]s to group closely-related hints (such
as two solutions to a puzzle.)  In any case, use [subject]s to avoid
having large numbers of selections (20 or more) at one time.   GIF maps
may be placed in their own separate "topic."  This is often easier than
forcing maps into topics.  It also gives you the chance to make [comment]s
about the maps in general.  (The warning could state that there are no
hints available in the maps.)
 
 6. Only include as many [credit] sections as are necessary.  If you wrote
all parts of a file, do not include one [credit] that says "I wrote the
hints" and another that says "I drew the GIF maps."  Simply state that you
wrote the entire file.  The title for [credit]s should only read something
like "About the author..."  Do not try to fit your [credit]s into the title
line.  Also remember to include other people's copyrights or credits in your
files, if you did not write the complete file.  Of course, make sure you have
permission to include anything you did not write.
 
 7. Please keep your text "neat."  Include at least one space after
punctation marks (you can also place two spaces between sentences).  Start
each line with a capital letter, etc.  Do not use ellipses ("...") in hints.
Ellipses were often used in older 88a files to warn the user that there
was a multi-line hint, and that there was a continuation.  You can use true
multi-line hints to accomplish the same thing.  If there is a need to exceed
the ten-line limit for hints, you are probably giving away too much, so
shorten it.  Try to observe proper spelling, capitalization, punctuation,
and grammar.  (You might want to run your file through a spell-checker.)  No
matter how you format you text, keep your formatting consistent throughout the
file.
 
 8. Do not place comments in [credit] sections, or vice-versa.  Any needed
warnings or explanations on how the file is written should be included in
[comment]s.  Information on the authors of portion of the file (or on the
game's authors) should be included in [credit]s.
 
 9. Always keep a back-up copy of your uncompiled file.  Most compilers will
compute a CRC for the file, so you cannot make changes once the file in
compiled.  "Uncompilers" will not be provided, so you will not be able to
update your file if the uncompiled version.

10. I have found it helpful to work with a copy of a walkthru while writing
the UHS file.  Although you shouldn't copy text directly from someone else's
walkthru, you should use it to make sure that you did not leave out any
major points.  When writing your own walkthru, there is no need to go into
extreme detail.  All you really need to do is write a "plot summary" while
playing the game.  If your plot summary is complete, then your hints should
also be complete.  You may also use point lists as a guideline, although do
not explain how to find "frivilous" points (such as getting 1 point for
looking at a particular sign).  However, feel free to explain any side
puzzles.

11. Whenever possible, list all known solutions to a given situation, and
include all plot branches.

12. Do not duplicate the same question in several different areas.  If a
question is important enough that it needs to be duplicated, place it in a
separate section, so that duplication can be avoided and the file shortened.

13. Remember that certain UHS readers will use proportional type faces.  If
you try to line up text to draw ASCII maps (for example), your columns will
not align properly on those readers.  Use GIF maps for any situations where
proper alignment is crucial.

14. If your compiler allows you to specify an 88a header file, do not place
any game hints in the header.  Readers should be available for
IBM-compatibles (both DOS and Windows), Amigas, and Macintoshes.  If the
game for which you are writing hints does not have a 91a reader, write and
compile a file in 88a format.  The extra 91a data placed on the end will be
useless to others, and having two distinct file sections will only confuse
those with 91a readers.

