mirror of
https://github.com/ganelson/inform.git
synced 2024-07-05 00:24: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.
|
||
|