mirror of
https://github.com/ganelson/inform.git
synced 2024-07-07 17:44:22 +03:00
266 lines
12 KiB
Plaintext
266 lines
12 KiB
Plaintext
|
Indexing the Inform Documentation -- thoughts and self-reminders
|
|||
|
(Andrew Plotkin, January-February 2013)
|
|||
|
|
|||
|
* Meandering generalities
|
|||
|
|
|||
|
Indexing a manual is difficult, *crucial* work. A reader approaches
|
|||
|
bearing not just curiosity, but a concrete problem which she must
|
|||
|
solve. Somewhere in your manual is the answer. How do you get the
|
|||
|
answer in front of her?
|
|||
|
|
|||
|
The naive plan would be to run through the manual, look at each bit
|
|||
|
of information, give it a name, and alphabetize the resulting list.
|
|||
|
This cannot be sufficient. The hypothetical reader does not know what
|
|||
|
she is looking for; or if she does, she does not know what it is
|
|||
|
called. The hypothetical reader is a worst-case scenario of confusion
|
|||
|
-- rather, *every possible* worst-case scenario.
|
|||
|
|
|||
|
(One might compare the hypothetical *player* of interactive fiction --
|
|||
|
confused by a puzzle, uncertain of your clues, liable to misinterpret
|
|||
|
what you wrote and overinterpret what you did not intend. One might
|
|||
|
spin this comparison into an entire game about hunting information in
|
|||
|
some vast Borgesian library. One might run this parenthetical off the
|
|||
|
deep end of the metaphor pool and drown it.)
|
|||
|
|
|||
|
In short, the approach cannot be "Index the contents of chapter X."
|
|||
|
Rather: "The game designer has a question. Chapter X has the answer.
|
|||
|
What term, or terms, has the designer just searched for?" Write from
|
|||
|
inside the reader's head. (Thus, we have a comprehensive entry for
|
|||
|
"rooms"; but we also include "places: see rooms" and "locations: see
|
|||
|
rooms".)
|
|||
|
|
|||
|
The second lesson is that the reader learns from the index. We are
|
|||
|
creating a lesson, not merely a list of pointers. The organization of
|
|||
|
the index should reflect how Inform itself is conceptually organized.
|
|||
|
Also, index terms should carry as much information as can be packed
|
|||
|
in. (Thus, the entry for "lighted" notes that this is a *property*
|
|||
|
which applies to *rooms*, and its opposite is "dark".)
|
|||
|
|
|||
|
This context aids the reader on both ends. Perhaps she will discover
|
|||
|
her answer without having to consult the manual at all. Or, failing
|
|||
|
that, she may learn enough to search better. (A designer interested in
|
|||
|
brass lanterns would pass over "lighted" and alight on "lit", which
|
|||
|
applies to *things*.)
|
|||
|
|
|||
|
* Specifics (and examples)
|
|||
|
|
|||
|
Terms should often -- perhaps usually -- be indexed in more than one
|
|||
|
place.
|
|||
|
|
|||
|
- Each property is indexed both under its own name and in a catalogue
|
|||
|
of all properties: "enterable", "properties: catalogue: enterable"
|
|||
|
|
|||
|
- An either/or property will be indexed under its own name *and* its
|
|||
|
opposite: "open/closed", "closed/open".
|
|||
|
|
|||
|
- Any reference to defining a new X should be indexed under both "X"
|
|||
|
and "defining: X".
|
|||
|
|
|||
|
- The pages of the Index panel are triply indexed: their own name,
|
|||
|
"Index", and "user interface".
|
|||
|
|
|||
|
- "if" phrases automatically generate two references, with and without
|
|||
|
the "if" at the beginning. "say" phrases likewise generate two
|
|||
|
references.
|
|||
|
|
|||
|
|
|||
|
Every time such a term is mentioned, we have to include both (or all)
|
|||
|
of the index references. To facilitate this, we generally keep them in
|
|||
|
a single source paragraph. The paragraph can then be copied and pasted
|
|||
|
between chapters.
|
|||
|
|
|||
|
- When you add a reference to a property, find an existing example of
|
|||
|
its index reference and copy/paste the entire paragraph.
|
|||
|
|
|||
|
- Similarly, if you add a new property reference, use an existing one
|
|||
|
for a template, so that it shows up in all the right places.
|
|||
|
|
|||
|
- If you decide to rephrase an entry, make sure you rephrase every
|
|||
|
instance of it.
|
|||
|
|
|||
|
- If you want to mention an "if" or "say" phrase (outside the section
|
|||
|
where it is defined), you must reference it twice, as noted above.
|
|||
|
For example:
|
|||
|
^^{+to+say "[bold type]"} ^^{+tosay+"[bold type]"}
|
|||
|
|
|||
|
|
|||
|
In some cases, it is better to create a cross-reference ("X: see Y")
|
|||
|
than to repeat an entry.
|
|||
|
|
|||
|
- When a group entry is bulky, repeating it in two places would be a
|
|||
|
waste of space. (Thus, we have "creating: see defining" rather than
|
|||
|
trying to duplicate the very large "defining" entry. Also, while
|
|||
|
major kinds such as "room" appear under "kinds: catalogue", we
|
|||
|
add a "see also: rooms" rather than duplicating the whole "rooms"
|
|||
|
group.)
|
|||
|
|
|||
|
- When the reader has looked up a non-standard term, it may be better
|
|||
|
to cross-reference to the standard one, so that the reader is
|
|||
|
exposed to it. (Thus, we have "places: see rooms".)
|
|||
|
|
|||
|
- Similarly, if the reader has looked for a short term which is not
|
|||
|
self-explanatory, cross-refer to a longer, clearer one. (Thus,
|
|||
|
"reviews: see chapter reviews".)
|
|||
|
|
|||
|
- I have indexed each mark of punctuation twice ("!" and "punctuation:
|
|||
|
exclamation mark"). However, I didn't bother with a third entry
|
|||
|
("exclamation mark"), because I ran out of energy. Instead, I put in
|
|||
|
a cross-reference ("exclamation mark -- see punctuation: exclamation
|
|||
|
mark").
|
|||
|
|
|||
|
|
|||
|
If an index term is short, provide context with a comma, or in
|
|||
|
brackets, or in a category label. The reader will be more oriented if
|
|||
|
she knows what she is looking at.
|
|||
|
|
|||
|
- Category labels currently in use: "action", "action variable",
|
|||
|
"activity", "adjective", "assertion", "bibliographic data",
|
|||
|
"constant", "extension", "global variable", "grammar token", "kind",
|
|||
|
"of source text", "outcome phrase", "phrase", "property",
|
|||
|
"relation", "relation verb", "say phrase", "testing command",
|
|||
|
"use option", "user interface", "web site".
|
|||
|
|
|||
|
- Note that most of these are I7 classes or syntactic entities, but
|
|||
|
some are "merely" descriptive. (We have indexed the five heading
|
|||
|
levels as "chapter (of source text)", "section (of source text)",
|
|||
|
etc.)
|
|||
|
|
|||
|
|
|||
|
A verbose, clear entry is better than a terse one.
|
|||
|
|
|||
|
- I have entries for "hiding things carried by other characters" and
|
|||
|
"hiding things from room descriptions by making them scenery". No
|
|||
|
shame.
|
|||
|
|
|||
|
|
|||
|
For phrases, assertions, properties, and adjectives, provide type and
|
|||
|
argument information.
|
|||
|
|
|||
|
- This is auto-generated for phrase definitions, but we have to supply
|
|||
|
it for assertions, properties, etc.
|
|||
|
|
|||
|
- For either/or properties, we say "prop / opposite (TYPE) property".
|
|||
|
For other properties, we say "prop of (TYPE) property". (The "of"
|
|||
|
mimics how properties are used in source text: "closed trunk",
|
|||
|
"open trunk", "description of trunk".)
|
|||
|
|
|||
|
- Constants and global variables are rendered *without* brackets,
|
|||
|
because nothing is being slotted into the text. Instead, we use an
|
|||
|
em-dash, and the "unbracketed" option. Thus: "pi (— real number)",
|
|||
|
"command prompt (— text)", and the brackets disappear from the
|
|||
|
rendered page.
|
|||
|
|
|||
|
|
|||
|
Redundancy is good, but redundancy in a small space is bad.
|
|||
|
|
|||
|
- There is no entry for "italics", because the phrase "[italic type]"
|
|||
|
is in the right spot, and suffices. (On the other hand, I included
|
|||
|
both the command "UNDO" and the use option "undo prevention",
|
|||
|
because they seemed not quite identical.)
|
|||
|
|
|||
|
- The entries for each major kind (rooms, things, containers, etc)
|
|||
|
have the "kind" category label. However, in the "kind: catalogue"
|
|||
|
entry -- which lists them all together -- we do not put the "kind"
|
|||
|
label on each entry. That would just be visual noise. The word is
|
|||
|
already visible in the entry header.
|
|||
|
|
|||
|
- I have not created entries for the relation verbs "carry",
|
|||
|
"carried", because they'd appear right next to "carrying (relation)"
|
|||
|
and refer to the same thing. On the other hand, I did add the
|
|||
|
relation verbs "in", "held" cross-referenced to the containment
|
|||
|
relation, and "worn" cross-referenced to the wearing relation.
|
|||
|
|
|||
|
- Just to complicate life, I also added the *adjectives* "worn",
|
|||
|
"carried", "held", because they are not identical to (though
|
|||
|
related to) the relation verbs.
|
|||
|
|
|||
|
|
|||
|
There is no substitute for looking at the generated index, reading through
|
|||
|
some newly-added entries, and checking whether they flow clearly.
|
|||
|
|
|||
|
- While you're at it, check that they appear in the right place.
|
|||
|
|
|||
|
- Watch out for group entries that have gotten split! If you add a
|
|||
|
reference to "things: zorking", you will wind up with two adjacent
|
|||
|
"things" entry groups. This is because you left off the category
|
|||
|
tag; it should be "things+kind+: zorking". As always, look at
|
|||
|
existing references and copy their style.
|
|||
|
|
|||
|
- Keep an eye out for group entries that have exactly one sub-entry.
|
|||
|
Squash these back into a single entry. (Unless there's a reference
|
|||
|
for the group-level entry! "Animals: rideable" remains split,
|
|||
|
because there are references for "animals".)
|
|||
|
|
|||
|
|
|||
|
Occasionally one needs to index a term containing (or comprising) the
|
|||
|
special characters used by indoc's indexer: colon, curly braces, round
|
|||
|
brackets. The backslash is the escape character to solve this problem.
|
|||
|
|
|||
|
- A backslash followed by a (decimal) number renders as that ASCII
|
|||
|
(or Unicode) character: \58 is ":", \123 is "{", \125 is "}",
|
|||
|
\40 is "(", \41 is ")", \92 is a literal backslash.
|
|||
|
|
|||
|
- A backslash followed by a non-digit is literally that character.
|
|||
|
This works for \(, \), and \\. It will not work for colon or
|
|||
|
curly braces, due to the way indoc parses index terms.
|
|||
|
|
|||
|
- This backslash notation is only meaningful inside an index term!
|
|||
|
It doesn't work all the way across the document.
|
|||
|
|
|||
|
|
|||
|
Assorted miscellaneous decisions:
|
|||
|
|
|||
|
- In the WII source document, I have defined most terms in groups at
|
|||
|
the top of the section. Short in-passing references may be defined
|
|||
|
in-line, but if a term is liable to appear in several sections, it
|
|||
|
should be grouped at the top to make it more visible to the editor.
|
|||
|
|
|||
|
- In my earlier index for I7-6G60, I was clever about condensing
|
|||
|
entries with common prefixes ("to: be, decide, say...") and
|
|||
|
about omitting words ("comma, displaying serial"). This is not
|
|||
|
the good kind of clever. Spell things out.
|
|||
|
|
|||
|
- "Locksmith by Emily Short" is used as an example in several
|
|||
|
sections; I have not indexed most of these.
|
|||
|
|
|||
|
- "Square brackets" is plural because there are two of them. "Question
|
|||
|
mark" is singular because there's only one (that Inform cares about).
|
|||
|
|
|||
|
- I have put the "kind" category label only on kinds of things, not kinds
|
|||
|
of value. "Number" and "text" appear so frequently (and have their own
|
|||
|
sections) that I don't want to mix them into the kinds catalogue.
|
|||
|
|
|||
|
- There are categories for both commands ({>VERSION}) and actions
|
|||
|
({examining+action+}). I use the former for out-of-world and
|
|||
|
debugging commands; the latter for world-model commands. I don't
|
|||
|
index actions that are only mentioned by way of example. (Many bits
|
|||
|
of sample code refer to the eating action, but it's only indexed
|
|||
|
when we talk about eating food and the "edible" property.)
|
|||
|
|
|||
|
- When a phrase begins with a bracketed type, such as "(time) after
|
|||
|
(time)", the bracketed parts should not be counted for alphabetization.
|
|||
|
This requires a triple-caret line to set the alphabetization, e.g:
|
|||
|
^^^{+to+(time) after (time) --> after}
|
|||
|
I tried tweaking indoc to do this automatically, but it broke too many
|
|||
|
other things, so it has to be done manually. (However, it *is* done
|
|||
|
automatically for the alternate, shortened form of "if" and "say"
|
|||
|
phrases. Sorry about the complexity. This was a subcase that did the
|
|||
|
right thing nearly all the time.)
|
|||
|
|
|||
|
- When indexing a phrase or activity, we sometimes want to add a
|
|||
|
second reference under part of its name. For example:
|
|||
|
inventory details –– printing inventory details of something
|
|||
|
Note that this is not like "Short, Emily" or "undo, disabling". We
|
|||
|
want to include the entire phrase/activity name, because it is
|
|||
|
an I7 defined symbol. I have used a double en-dash as the separator
|
|||
|
in these cases. (Not an em-dash, because these lines are in a fixed-
|
|||
|
width font and an em-dash wouldn't be wide enough. A comma doesn't
|
|||
|
look great either.)
|
|||
|
|
|||
|
- I did not index anything in 24.18 through 24.23. That's the long
|
|||
|
section about polishing the index map. It's too much detail for too
|
|||
|
narrow a topic. If you want to know about that stuff, you are
|
|||
|
referred to 24.17 "Improving the index map" and can read forward
|
|||
|
from there.
|
|||
|
|