Added READMEindexing document to explain indexing.
[dwarf-doc.git] / dwarf5 / READMEindexing
1
2 ---Introduction
3
4 We do two sorts of 'index' entries:  indexing and linking.
5
6 There are specific commands to do the indexing in Latex, but
7 we use local commands rather than directly using \index
8 to save redundant typing and to make future revisions easier.
9
10 Where terms are actually defined in the document (as opposed
11 to simply being referenced) each reference to the term
12 is made an active link (in pdf terms) to the definition.
13 Of course the command also indexes the link.
14
15 ---Indexing
16
17 The actual command definitions in dwarf5.tex are:
18 \newcommand{\addtoindex}[1]{#1\index{#1}}
19 \newcommand{\addtoindexi}[2]{#1\index{#2}}
20 \newcommand{\noindex}[1]{#1}
21
22 Where a word or phrase is to be indexed.
23
24 The \noindex case indicates the word or phrase is to be
25 inserted as-is, not indexed.   So that readers of the
26 latex source can know someone considered indexing a word
27 that looked like it should be indexed
28 but decided not to index it.   This is mostly necessary
29 for form-class instances as some form-class words are used
30 in ordinary English, like 'block'.  When searching a document
31 for index omissions we will often want to distinguish
32 new uses from old (and already-considered) instances and
33 the \noindex command helps us do that.
34
35 ---Indexing special cases
36 The special cases are index entries that say 
37 'See ' instead of a page reference (documented
38 in latex and called cross-references), entries
39 that are indexed with a phrase, and entries that are indexed
40 with a phrase with a comma.
41    
42 (these taken from DWARF4 FIXME use dwarf5 examples)
43    address selection        See base address selection
44    abstract instance tree
45    array, declaration of type
46    array, descriptor for
47
48 standard case where we index a word as-is.
49 \addtoindex{document}
50
51 This generates the subindex case, the index spelling does not match
52 what the text must say:
53 \addtoindexi{array}{array!declaration of type}
54
55 This generates an index with See (See can be any phrase, not
56 just .
57 The | here is uniquely handled by latex so it is not confused as
58 a math character.
59 \addtoindexi{address selection}{address selection|see{base address selection}}
60
61
62
63
64 ---Linking
65
66 The actual command definitions in dwarf5.tex are:
67 \newcommand{\livelink}[2]{\hyperlink{#1}{#2}\index{#2} }
68 \newcommand{\livetarg}[2]{\hypertarget{#1}{#2}\index{#2}}
69 \newcommand{\livetargi}[3]{\hypertarget{#1}{#2}\index{#3}}
70 \newcommand{\nolink}[1]{#1}
71
72 We want terms like DW_TAG_common (which is all the DW_* terms)
73 to both be indexed and also to be a 'live link' in a pdf to
74 a definition of the term.  The intent is that clicking
75 on the word or phrase in the document switches you to
76 a display of the definition.
77
78 Attributes in DWARF may have multiple definition points, so
79 for example DW_AT_abstract_origin links one to the attribute table
80 and that in turn links to the 3 distinct definitions.
81 Other than Attributes though, links are usually directly
82 to the definition.
83
84 The first argument in a livelink/livetarg/livetargi command
85 is a string that must be unique to the target, it is used
86 by latex to tie each link to its single target location.
87
88 Sentences referencing the form-class words should also be
89 live links. For common English form-class words 
90 like 'address' or 'block' there can be many word uses
91 we do not want to link or index, so \nolink or \noindex
92 let us designate those instances for folks working with
93 the latex document source.
94
95 The \livetargi instance lets us make the index entry be
96 a phrase or spelling distinct from the live link word.
97
98