1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
-
-
-
-
+
+
+
+
-
-
-
-
-
-
+
-
+
+
-
+
+
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
+
+
+
-
+
+
+
+
+
+
+
+
+
+
|
# 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. (?)
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 entry in the index and whose destination is the place where the pin appears.
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.
A pin specifies the *name* of the index entry that should tie back to it:
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”.
> My favorite book is ◊pin{◊cite{Jonathan Strange and Mr Norrell}}.
> My favorite book is ◊pin{◊cite{Jonathan Strange}}.
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”.
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 *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 ◊def["Doors"]{door} is an articulating barrier.
> A ◊defpin{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”.
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.
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}
The above adds a link to its article from an index subentry with the name “◊cite{Writing books}” and the key “writingbooksexplained”.
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.
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 "")`
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”.
|
