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