Cross-references

A cross-reference has a source (the article and particular place in that article where the reference appears) and a destination (the place to which the reference directs you). The destination is always a particular place within an article.

Index entries

Entries in the index have these properties:

• A name, which is what the reader sees, and which preserves information such as case and formatting.
• An entry and subentry
• A key, which by default is a normalization of the name according to these steps:
  1. Strip formatting if present, and convert to lowercase
  2. If the name originally contained no formatting, replace the first comma-space with an exclamation mark (which marks the entry/subentry boundary)
  3. If the name originally contained no formatting, in the entry portion replace a trailing “ies” with “y” and remove a trailing “s”
  4. In both the entry and subentry portions, delete all non-alphanumeric characters

Index entries are collected together when they have the same name, not when they have the same key. (?)

Pins

A pin creates a cross-reference whose source is an entry in the index and whose destination is the place where the pin appears.

A pin specifies the name of the index entry that should tie back to it:

Below is a ◊pin["Doors, colors of"]{doors in our house and their colors}…

The above adds a link to that passage in the text from an index subentry “Doors, colors of”, which appears under the entry “doors“. The name of the index entry is "Doors, colors of" and its key is “door!colorsof”.

To create a pin for a titled work:

My favorite book is ◊pin{◊cite{Jonathan Strange and Mr Norrell}}.

For the index entry that will link to the above passage, the name is ◊cite{Jonathan Strange and Mr Norrell} and the key is “jonathanstrangeandmrnorrell”.

Defs

A def is a kind of pin that, in addition to creating a cross-reference from an index entry, can be linked directly from another article. Like pins, defs specify the names of the index entries that point back to them, but they modify the names provided.

A ◊def["Doors"]{door} is an articulating barrier.

The above adds a link to that place in the text from an index subentry “Doors, definition of” — the subentry is added automatically. The key of the entry is “door!definitionof”.

Formatting: in a body of text, a def is italicized, and links back to its index entry.

Titles

A title in an article works like a def, but it does not automatically tack on the “definition of” subentry and it surrounds its contents with a ◊cite tag.

◊title{Writing books, explained}

The above adds a link to its article from an index subentry with the name “◊cite{Writing books}” and the key “writingbooksexplained”.

Formatting: A title links back to its index entry.

Refs

A ref links directly to a def (not to the index). However, it also adds a cross-reference from an index entry back to itself.

Install the ◊ref{doors} so that they can be opened from the inside.

The above creates a direct link (resolved at template render time) to the def tag for the key “door” in whichever article it appears. At the same time, a link to the ref tag is added from an index entry that has the key (?) of “door”.