inform7/indoc/Materials/Indexing-Guidelines.txt

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.