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{\addtoindexx}[1]{\index{#1}}
  21 \newcommand{\noindex}[1]{#1}
  22
  23 Where a word or phrase is to be indexed.
  24
  25 The \noindex case indicates the word or phrase is to be
  26 inserted as-is, not indexed.   So that readers of the
  27 latex source can know someone considered indexing a word
  28 that looked like it should be indexed
  29 but decided not to index it.   This is mostly necessary
  30 for form-class instances as some form-class words are used
  31 in ordinary English, like 'block'.  When searching a document
  32 for index omissions we will often want to distinguish
  33 new uses from old (and already-considered) instances and
  34 the \noindex command helps us do that.
  35
  36 ---Indexing special cases
  37 The special cases are index entries that say
  38 'See ' instead of a page reference (documented
  39 in latex and called cross-references), entries
  40 that are indexed with a phrase, and entries that are indexed
  41 with a phrase with a comma.
  42
  43 (these taken from DWARF4 FIXME use dwarf5 examples)
  44    address selection        See base address selection
  45    abstract instance tree
  46    array, declaration of type
  47    array, descriptor for
  48
  49 standard case where we index a word as-is.
  50 \addtoindex{document}
  51
  52 This generates the subindex case, the index spelling does not match
  53 what the text must say:
  54 \addtoindexi{array}{array!declaration of type}
  55
  56 This generates an index with See (See can be any phrase, not
  57 just .
  58 The | here is uniquely handled by latex so it is not confused as
  59 a math character.
  60 \addtoindexi{address selection}{address selection|see{base address selection}}
  61
  62
  63 Use \textgreater  and \textless to represent < and >
  64 in indexes (and other contexts).  For example
  65        \textless caf\textgreater   results in <caf>
  66 oddly enough.
  67
  68
  69 ---Linking
  70
  71 The actual command definitions in dwarf5.tex are:
  72 \newcommand{\livelink}[2]{\hyperlink{#1}{#2}\index{#2} }
  73 \newcommand{\livetarg}[2]{\hypertarget{#1}{#2}\index{#2}}
  74 \newcommand{\livetargi}[3]{\hypertarget{#1}{#2}\index{#3}}
  75 \newcommand{\nolink}[1]{#1}
  76
  77 We want terms like DW_TAG_common (which is all the DW_* terms)
  78 to both be indexed and also to be a 'live link' in a pdf to
  79 a definition of the term.  The intent is that clicking
  80 on the word or phrase in the document switches you to
  81 a display of the definition.
  82
  83 --- Linking of attributes
  84 Attributes in DWARF may have multiple definition points, so
  85 for example DW_AT_abstract_origin links one to the attribute table
  86 and that in turn links to the 3 distinct definitions.
  87 Other than Attributes though, links are usually directly
  88 to the definition.
  89
  90 It is critical that the hypertarget and livelink be
  91 separated to avoid problems with latex. Example:
  92
  93 out\dash of\dash line instance
  94 \hypertarget{chap:DWATabstractoriginoutoflineinstance}
  95 makes use of
  96 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
  97
  98 If the 'makes use of' or some other text is not between
  99 the hypertarget and hyperlink latex produces output text of
 100 chap:DWATabstractorigin instead of thinking of it as a link.
 101
 102 It's also useful to put the hypertarget before the livelink
 103 for the attribute use in the sentence because then when your
 104 reader takes you to the hypertarget (via a mouse click)
 105 you will see the attribute instance (assumuing
 106 your  viewer puts the 'target' location at the top of
 107 the viewing area).
 108
 109 --- Linking (continued)
 110
 111 The first argument in a livelink/livetarg/livetargi command
 112 is a string that must be unique to the target, it is used
 113 by latex to tie each link to its single target location.
 114
 115 Sentences referencing the form-class words should also be
 116 live links. For common English form-class words
 117 like 'address' or 'block' there can be many word uses
 118 we do not want to link or index, so \nolink or \noindex
 119 let us designate those instances for folks working with
 120 the latex document source.
 121
 122 The \livetargi instance lets us make the index entry be
 123 a phrase or spelling distinct from the live link word.
 124
 125