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

• Index Heading: A word or phrase that appears in the index.
• Index Subheading: A heading that appears under another heading. Every heading has at least one subheading (“”).
• Index Link: A reference from an index entry back to an article
• Index Entry: A heading, a list of subheadings and their links

Index entries are collected together when their main headings are identical. For example, “doors” and “Doors” would be the headings of separate entries.

Pins

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

A pin’s has a key and contents. The pin tag accepts either one or two arguments; if only one is given, it serves as both the key and the contents; if two, the first is the key and the second is the content. The key specifies the heading and subheading of the index entry that should tie back to it.

• If the pin is given two arguments and if the key consists of a string and contains a comma-space, the portion before the first comma-space is the heading and the portion after the first comma-space is the subheading.
• Otherwise the entire key is used as the heading and the subheading is empty.

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

Results in (index-entry #:heading "Doors" #:subheading "colors of")

To create a pin for a titled work:

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

Results in (index-entry #:heading '(cite "Jonathan Strange") #:subheading "")

Defs

A defpin 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.

A ◊defpin{door} is an articulating barrier.

Results in (index-entry #:heading "door" #:subheading "definition of") — the subentry is added automatically.

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

Titles

A title in an article also works like a pin, creating a link back to itself from an index entry whose name is a cite tag surrounding its contents.

◊title{Writing books, explained}

Results in (index-entry #:heading '(title "Writing books, explained") #:subheading"")

Formatting: A title links back to its index entry.

Refs

A ref links directly to the site of 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 first article linked in the index entry with the heading “doors” and the subheading “definition of” * Also creates (index-entry #:heading "doors" #:subheading "")

To reference another article:

◊ref[#:article "Writing books, explained"]

• Creates a link to the first article linked in the index entry for (title "Writing books, explained")
• Also creates (index-entry #:heading '(title "Writing books, explained") #:subheading "references to")

Mechanics

At compile-time, all pins, defpins and titles add themselves to the metas as xexprs.

A separate process iterates over all the articles and collects the index entries.