D 2022-01-02T04:48:39.073
L Ideas\sScratchpad
N text/x-markdown
P b5c47676a828f74dd37b770d81e5ec8c82b3b07d0c2e8dff707ab087316fcc29
U joel
W 3689
# 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.
Z 88bc5a26eb0521d66b7d118979e83067
