◊(Local Yarn Code "Ideas Scratchpad")


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.


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 "")


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.


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.


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")


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.