Misc corrections Chpt 6 thru App A
[dwarf-doc.git] / dwarf5 / latexdoc / examples.tex
index 5a3c960..c3b1954 100644 (file)
@@ -12,8 +12,13 @@ various aspects of the DWARF debugging information format.
 
 Figure \refersec{fig:compilationunitsandabbreviationstable}
 depicts the relationship of the abbreviations tables contained
-in the .debug\_abbrev section to the information contained in
-the .debug\_info section. Values are given in symbolic form,
+\addtoindexx{abbreviations table!example}
+\addtoindexx{.debug\_abbrev example}
+\addtoindexx{.debug\_info example}
+in the \addtoindex{.debug\_abbrev}
+section to the information contained in
+the \addtoindex{.debug\_info}
+section. Values are given in symbolic form,
 where possible.
 
 The figure corresponds to the following two trivial source files:
@@ -33,7 +38,7 @@ typedef char* strp;
 %\centering
 \begin{minipage}{0.4\textwidth}
 \centering
-Compilation Unit 1: .debug\_info
+Compilation Unit 1: \addtoindex{.debug\_info}
 \begin{framed}
 \scriptsize
 \begin{alltt}
@@ -74,7 +79,7 @@ e2
 %
 %
 \end{framed}
-Compilation Unit 2: .debug\_info
+Compilation Unit 2: \addtoindex{.debug\_info}
 \begin{framed}
 \scriptsize
 \begin{alltt}
@@ -101,7 +106,7 @@ e2
 \hfill
 \begin{minipage}{0.4\textwidth}
 \centering
-Abbreviation Table: .debug\_abbrev
+Abbreviation Table: \addtoindex{.debug\_abbrev}
 \begin{framed}
 \scriptsize
 \begin{alltt}
@@ -160,8 +165,9 @@ using DWARF.
 
 \subsection{Fortran 90 Example}
 \label{app:fortran90example}
-Consider the Fortran 90 source fragment in 
-Figure \refersec{fig:fortran90examplesourcefragment}.
+Consider the \addtoindex{Fortran 90} source fragment in 
+\addtoindexx{array type entry!examples}
+Figure \referfol{fig:fortran90examplesourcefragment}.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -179,7 +185,10 @@ end do
 \end{figure}
 
 For allocatable and pointer arrays, it is essentially required
-by the Fortran 90 semantics that each array consist of two
+by the \addtoindex{Fortran 90} semantics that each array consist of 
+\addtoindexx{descriptor!array}
+two
+\addtoindexx{array!descriptor for}
 parts, which we here call 1) the descriptor and 2) the raw
 data. (A descriptor has often been called a dope vector in
 other contexts, although it is often a structure of some kind
@@ -192,12 +201,14 @@ the ``variable'' is allocated or associated).
 
 For concreteness, suppose that a descriptor looks something
 like the C structure in 
-Figure \refersec{fig:fortran90exampledescriptorrepresentation}.
+Figure \referfol{fig:fortran90exampledescriptorrepresentation}.
 Note, however, that it is
 a property of the design that 1) a debugger needs no builtin
 knowledge of this structure and 2) there does not need to
 be an explicit representation of this structure in the DWARF
-input to the debugger.
+input to the 
+\addtoindexx{Fortran 90}
+debugger.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -214,7 +225,8 @@ struct desc {
     } dims[63];
 };
 \end{lstlisting}
-\caption{Fortran 90 example: descriptor representation} \label{fig:fortran90exampledescriptorrepresentation}
+\caption{Fortran 90 example: descriptor representation}
+\label{fig:fortran90exampledescriptorrepresentation}
 \end{figure}
 
 
@@ -241,14 +253,17 @@ to the “raw data” (the real data, the only thing around
 that can be the object).
 
 If an object has a descriptor, then the DWARF type for that
-object will have a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. If an object
+object will have a 
+\livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. If an object
 does not have a descriptor, then usually the DWARF type for the
-object will not have a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}. (See the following
-Ada example for a case where the type for an object without
+object will not have a 
+\livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}. 
+(See the following
+\addtoindex{Ada} example for a case where the type for an object without
 a descriptor does have a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. In
 that case the object doubles as its own descriptor.)
 
-The Fortran 90 derived type array\_ptr can now be redescribed
+The \addtoindex{Fortran 90} derived type array\_ptr can now be redescribed
 in C\dash like terms that expose some of the representation as in
 
 \begin{lstlisting}
@@ -276,7 +291,9 @@ within an entity of the given type
 \end{enumerate}
 
 
-The DWARF description is shown in 
+The DWARF description is shown 
+\addtoindexx{Fortran 90}
+in 
 Section \refersec{app:fortran90exampledwarfdescription}.
 
 \subsection{Fortran 90 example: DWARF description}
@@ -288,12 +305,12 @@ Section \refersec{app:fortran90exampledwarfdescription}.
 1\$: \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
         ! No name, default (Fortran) ordering, default stride
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to REAL)
-        \livelink{chap:DWATassociated}{DW\-\_AT\-\_associated}(expression= ! Test 'ptr\_assoc' flag
+        \livelink{chap:DWATassociated}{DW\-\_AT\-\_associated}(expression= ! Test 'ptr\_assoc' \nolink{flag}
             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == offset(ptr\_assoc)
             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref}
-            \livelink{chap:DWOPlit1}{DW\-\_OP\-\_lit1} ! mask for 'ptr\_assoc' flag
+            \livelink{chap:DWOPlit1}{DW\-\_OP\-\_lit1} ! mask for 'ptr\_assoc' \nolink{flag}
             \livelink{chap:DWOPand}{DW\-\_OP\-\_and})
         \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}(expression= ! Get raw data address
             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
@@ -341,13 +358,13 @@ Section \refersec{app:fortran90exampledwarfdescription}.
         ! No name, default (Fortran) ordering, default stride
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 3\$)
         \livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated}(expression=
-             ! Test 'ptr\_alloc' flag
+             ! Test 'ptr\_alloc' \nolink{flag}
             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == offset(ptr\_alloc)
             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref}
             \livetarg{chap:DWOPlit2}{DW\-\_OP\-\_lit2}
-             ! mask for 'ptr\_alloc' flag
+             ! mask for 'ptr\_alloc' \nolink{flag}
             \livelink{chap:DWOPand}{DW\-\_OP\-\_and})
         \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}(expression= ! Get raw data address
             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
@@ -379,7 +396,9 @@ Section \refersec{app:fortran90exampledwarfdescription}.
 \subsection{Fortran 90 example continued: DWARF description}
 \label{app:fortran90examplecontinueddwarfdescription}
 
-Suppose the program is stopped immediately following completion
+Suppose 
+\addtoindexx{Fortran 90 example}
+the program is stopped immediately following completion
 of the do loop. Suppose further that the user enters the
 following debug command:
 
@@ -483,8 +502,9 @@ would be different.
 \subsection{Ada Example}
 \label{app:adaexample}
 
-Figure \refersec{fig:adaexamplesourcefragment}
-illustrates two kinds of Ada parameterized array, one embedded in a record.
+Figure \referfol{fig:adaexamplesourcefragment}
+illustrates two kinds of \addtoindex{Ada} 
+parameterized array, one embedded in a record.
 
 
 \begin{figure}[here]
@@ -499,11 +519,13 @@ end record;
 
 OBJ2B : REC2;
 \end{lstlisting}
-\caption{Ada 90 example: source fragment} \label{fig:adaexamplesourcefragment}
+\caption{Ada 90 example: source fragment}
+\label{fig:adaexamplesourcefragment}
 \end{figure}
 
 VEC1 illustrates an (unnamed) array type where the upper bound
-of the first and only dimension is determined at runtime. Ada
+of the first and only dimension is determined at runtime. 
+\addtoindex{Ada}
 semantics require that the value of an array bound is fixed at
 the time the array type is elaborated (where elaboration refers
 to the runtime executable aspects of type processing). For
@@ -558,7 +580,7 @@ of this example and therefore not shown.
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("M")
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
 12\$: \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
-        ! No name, default (Ada) order, default stride
+        ! No name, default (\addtoindex{Ada}) order, default stride
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
 13\$:    \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
@@ -582,7 +604,7 @@ of this example and therefore not shown.
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to subtype TEENY at 21\$)
             \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location}(constant 0)
 28\$:   \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
-            ! No name, default (Ada) order, default stride
+            ! No name, default (\addtoindex{Ada}) order, default stride
             ! Default data location
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
 29\$:       \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
@@ -606,10 +628,11 @@ of this example and therefore not shown.
 \subsection{Pascal Example}
 \label{app:pascalexample}
 
-The Pascal source in 
-Figure \refersec{fig:packedrecordexamplesourcefragment}
-is used to illustrate the representation of packed unaligned bit
-fields.
+The Pascal \addtoindexx{Pascal example} source in 
+Figure \referfol{fig:packedrecordexamplesourcefragment}
+is used to illustrate the representation of packed unaligned
+\addtoindex{bit fields}.
+
 \begin{figure}[here]
 \begin{lstlisting}
 TYPE T : PACKED RECORD ! bit size is 2
@@ -625,7 +648,8 @@ F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
 F7 : T; ! bit offset is 37
 END;
 \end{lstlisting}
-\caption{Packed record example: source fragment} \label{fig:packedrecordexamplesourcefragment}
+\caption{Packed record example: source fragment}
+\label{fig:packedrecordexamplesourcefragment}
 \end{figure}
 
 The DWARF representation in 
@@ -643,8 +667,8 @@ Section \refersec{chap:datamemberentries}.
 
 \subsection{Packed record example: DWARF description}
 \label{app:packedrecordexampledwarfdescription}
-% DWARF4 had some entries here as DW_AT_member .
-% Those are fixed here to DW_TAG_member
+% DWARF4 had some entries here as \livelink{chap:DWATmember}{DW_AT_member} .
+% Those are fixed here to \livelink{chap:DWTAGmember}{DW_TAG_member}
 \begin{alltt}
 
 21\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} ! anonymous type for F2
@@ -658,9 +682,9 @@ Section \refersec{chap:datamemberentries}.
             \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}(0)
             \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(1)
         \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride}(2)
-        \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(4)
+        \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(4) \addtoindexx{bit size attribute}
 23\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} ! anonymous type for V
-        \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(39)
+        \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(39) \addtoindexx{bit size attribute}
         \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("F1")
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 10\$)
@@ -680,7 +704,7 @@ Section \refersec{chap:datamemberentries}.
             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("F7")
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 20\$) ! type T
             \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}(37)
-            \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(2) ! may be omitted
+            \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(2) \addtoindexx{bit size attribute}! may be omitted
      \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("V")
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 23\$)
@@ -693,8 +717,10 @@ Section \refersec{chap:datamemberentries}.
 
 
 The C++ example in 
-Figure \refersec{fig:namespaceexamplesourcefragment}
-is used to illustrate the representation of namespaces.
+Figure \referfol{fig:namespaceexamplesourcefragment}
+is used 
+\addtoindexx{namespace (C++)!example}
+to illustrate the representation of namespaces.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -732,12 +758,13 @@ int Foo::myfunc(int a)
     return myfunc2(3) + j + i + a + 2;
 }
 \end{lstlisting}
-\caption{Namespace example: source fragment} \label{fig:namespaceexamplesourcefragment}
+\caption{Namespace example: source fragment}
+\label{fig:namespaceexamplesourcefragment}
 \end{figure}
 
 
 The DWARF representation in 
-Section \refersec{app:namespaceexampledwarfdescription}
+Section \referfol{app:namespaceexampledwarfdescription}
 is appropriate.
 
 \subsection{Namespace example: DWARF description}
@@ -824,7 +851,7 @@ is appropriate.
 \label{app:memberfunctionexample}
 
 Consider the member function example fragment in 
-Figure \refersec{fig:memberfunctionexamplesourcefragment}.
+Figure \referfol{fig:memberfunctionexamplesourcefragment}.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -836,7 +863,8 @@ class A
 };
 void A::func1(int x) {}
 \end{lstlisting}
-\caption{Member function example: source fragment} \label{fig:memberfunctionexamplesourcefragment}
+\caption{Member function example: source fragment}
+\label{fig:memberfunctionexamplesourcefragment}
 \end{figure}
 
 
@@ -873,7 +901,7 @@ is appropriate.
             \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration}
             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("func1")
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
-            \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}(reference to 8\$)
+            \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}(reference to 8\$) \addtoindexx{object pointer attribute}
                 ! References a formal parameter in this 
                 ! member function
             ...
@@ -894,7 +922,7 @@ is appropriate.
              \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration}
              \livelink{chap:DWATname}{DW\-\_AT\-\_name}("func2")
              \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
-             \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}(reference to 11\$)
+             \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}(reference to 11\$) \addtoindexx{object pointer attribute}
              ! References a formal parameter in this 
              ! member function
              ...
@@ -924,7 +952,7 @@ is appropriate.
 
 Consider the simple source file and the resulting machine
 code for the Intel 8086 processor in 
-Figure \refersec{fig:linenumberprogramexamplemachinecode}.
+Figure \referfol{fig:linenumberprogramexamplemachinecode}.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -948,12 +976,21 @@ Figure \refersec{fig:linenumberprogramexamplemachinecode}.
     0x24c: ret
 7: 0x24d:
 \end{lstlisting}
-\caption{Line number program example: machine code} \label{fig:linenumberprogramexamplemachinecode}
+\caption{Line number program example: machine code}
+\label{fig:linenumberprogramexamplemachinecode}
 \end{figure}
 
 Suppose the line number program header includes the following
-(header fields not needed below are not shown):
-
+(header fields not 
+needed 
+\addtoindexx{line\_base}
+below 
+\addtoindexx{line\_range}
+are 
+\addtoindexx{opcode\_base}
+not 
+\addtoindexx{minumum\_instruction\_length}
+shown):
 
 
 \begin{alltt}
@@ -965,7 +1002,7 @@ line_range                15
 \end{alltt}
 
 
-Figure \refersec{tab:linenumberprogramexampleoneencoding}
+Table \referfol{tab:linenumberprogramexampleoneencoding}
 shows one encoding of the line number program, which occupies
 12 bytes (the opcode SPECIAL(m,n) indicates the special opcode
 generated for a line increment of m and an address increment
@@ -975,7 +1012,8 @@ of n).
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{lll}
-  \caption{Line number program example: one encoding} \label{tab:linenumberprogramexampleoneencoding} \\
+  \caption{Line number program example: one encoding}
+  \label{tab:linenumberprogramexampleoneencoding} \\
   \hline \\ \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
 \endfirsthead
   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
@@ -984,18 +1022,18 @@ of n).
 \endfoot
   \hline
 \endlastfoot
-DW\-\_LNS\-\_advance\-\_pc&LEB128(0x239)&0x2, 0xb9, 0x04 \\
+\livelink{chap:DWLNSadvancepc}{DW\-\_LNS\-\_advance\-\_pc}&LEB128(0x239)&0x2, 0xb9, 0x04 \\
 SPECIAL(2, 0)&0xb  & \\
 SPECIAL(2, 3)&0x38 & \\
 SPECIAL(1, 8)&0x82 & \\
 SPECIAL(1, 7)&0x73 & \\
-DW\-\_LNS\-\_advance\-\_pc&LEB128(2)&0x2, 0x2 \\
-DW\-\_LNE\-\_end\-\_sequence &&0x0, 0x1, 0x1 \\
+\livelink{chap:DWLNSadvancepc}{DW\-\_LNS\-\_advance\-\_pc}&LEB128(2)&0x2, 0x2 \\
+\livelink{chap:DWLNEendsequence}{DW\-\_LNE\-\_end\-\_sequence} &&0x0, 0x1, 0x1 \\
 \end{longtable}
 \end{centering}
 
 
-Table \refersec{tab:linenumberprogramexamplealternateencoding}
+Table \referfol{tab:linenumberprogramexamplealternateencoding}
 shows an alternate 
 encoding of the same program using 
 standard opcodes to advance
@@ -1005,7 +1043,8 @@ this encoding occupies 22 bytes.
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{lll}
-  \caption{Line number program example: alternate encoding} \label{tab:linenumberprogramexamplealternateencoding} \\
+  \caption{Line number program example: alternate encoding} 
+  \label{tab:linenumberprogramexamplealternateencoding} \\
   \hline \\ \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
 \endfirsthead
   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
@@ -1014,16 +1053,16 @@ this encoding occupies 22 bytes.
 \endfoot
   \hline
 \endlastfoot
-DW\-\_LNS\-\_fixed\-\_advance\-\_pc&0x239&0x9, 0x39, 0x2        \\
+\livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc}&0x239&0x9, 0x39, 0x2        \\
 SPECIAL(2, 0)&& 0xb        \\
-DW\-\_LNS\-\_fixed\-\_advance\-\_pc&0x3&0x9, 0x3, 0x0        \\
+\livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc}&0x3&0x9, 0x3, 0x0        \\
 SPECIAL(2, 0)&&0xb        \\
-DW\-\_LNS\-\_fixed\-\_advance\-\_pc&0x8&0x9, 0x8, 0x0        \\
+\livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc}&0x8&0x9, 0x8, 0x0        \\
 SPECIAL(1, 0)&& 0xa        \\
-DW\-\_LNS\-\_fixed\-\_advance\-\_pc&0x7&0x9, 0x7, 0x0        \\
+\livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc}&0x7&0x9, 0x7, 0x0        \\
 SPECIAL(1, 0) && 0xa        \\
-DW\-\_LNS\-\_fixed\-\_advance\-\_pc&0x2&0x9, 0x2, 0x0        \\
-DW\-\_LNE\-\_end\-\_sequence&&0x0, 0x1, 0x1        \\
+\livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc}&0x2&0x9, 0x2, 0x0        \\
+\livelink{chap:DWLNEendsequence}{DW\-\_LNE\-\_end\-\_sequence}&&0x0, 0x1, 0x1        \\
 \end{longtable}
 \end{centering}
 
@@ -1066,9 +1105,8 @@ stack pointer (R7) is the same as the CFA
 
 \end{itemize}
 
-The following 
-(Figure refersec{fig:callframeinformationexamplemachinecodefragments}
-are two code fragments from a subroutine called
+Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
+shows two code fragments from a subroutine called
 foo that uses a frame pointer (in addition to the stack
 pointer). The first column values are byte addresses. 
 % The \space is so we get a space after >
@@ -1093,17 +1131,17 @@ foo+76 add R7, R7, <fs>        ; Deallocate frame
 foo+80 jump R1 ; Return
 foo+84
 \end{lstlisting}
-\caption{Call frame information example: machine code fragments} \label{fig:callframeinformationexamplemachinecodefragments}
+\caption{Call frame information example: machine code fragments}
+\label{fig:callframeinformationexamplemachinecodefragments}
 \end{figure}
 
 
 An abstract table 
 (see Section \refersec{chap:structureofcallframeinformation}) 
-for the foo subroutine
-is shown in 
-Table \refersec{tab:callframeinformationexampleconceptualmatrix}.
+for the foo subroutine is shown in 
+Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
 Corresponding fragments from the
-.debug\_frame section are shown in 
+\addtoindex{.debug\_frame} section are shown in 
 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
 
 The following notations apply in 
@@ -1121,7 +1159,8 @@ Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{lllllllllll}
-  \caption{Call frame inforation example: conceptual matrix} \label{tab:callframeinformationexampleconceptualmatrix} \\
+  \caption{Call frame inforation example: conceptual matrix} 
+  \label{tab:callframeinformationexampleconceptualmatrix} \\
   \hline \\ \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
 \endfirsthead
   \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
@@ -1149,7 +1188,8 @@ foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{lll}
-  \caption{Call frame information example: common information entry encoding} \label{tab:callframeinformationexamplecommoninformationentryencoding} \\
+  \caption{Call frame information example: common information entry encoding} 
+  \label{tab:callframeinformationexamplecommoninformationentryencoding} \\
   \hline \\ \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
 \endfirsthead
   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
@@ -1239,8 +1279,9 @@ fde+44 && \\
 \section{Inlining Examples}
 \label{app:inliningexamples}
 The pseudo\dash source in 
-Figure \refersec{fig:inliningexamplespseudosourcefragment}
+Figure \referfol{fig:inliningexamplespseudosourcefragment}
 is used to illustrate the
+\addtoindexx{inlined subprogram call!examples}
 use of DWARF to describe inlined subroutine calls. This
 example involves a nested subprogram INNER that makes uplevel
 references to the formal parameter and local variable of the
@@ -1264,7 +1305,8 @@ inline procedure OUTER (OUTER_FORMAL : integer) =
 !
 OUTER(7);
 \end{lstlisting}
-\caption{Inlining examples: pseudo-source fragmment} \label{fig:inliningexamplespseudosourcefragment}
+\caption{Inlining examples: pseudo-source fragmment} 
+\label{fig:inliningexamplespseudosourcefragment}
 \end{figure}
 
 
@@ -1345,7 +1387,7 @@ Section \refersec{app:inliningexample1concreteinstance}.
 \label{app:inliningexample1abstractinstance}
 \begin{alltt}
     ! Abstract instance for OUTER
-    !
+    ! \addtoindexx{abstract instance!example}
 OUTER.AI.1.1:
     \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER")
@@ -1392,7 +1434,7 @@ INNER.AI.1.3:
 \label{app:inliningexample1concreteinstance}
 \begin{alltt}
 ! Concrete instance for call "OUTER(7)"
-!
+! \addtoindexx{concrete instance!example}
 OUTER.CI.1.1:
     \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
         ! No name
@@ -1445,36 +1487,47 @@ INNER.CI.1.3:
 
 In the second alternative we assume that subprogram INNER
 is not inlinable for some reason, but subprogram OUTER is
-inlinable. Each concrete inlined instance of OUTER has its
-own normal instance of INNER. The abstract instance for OUTER,
+inlinable. 
+\addtoindexx{concrete instance!example}
+Each concrete inlined instance of OUTER has its
+own normal instance of INNER. 
+The abstract instance for OUTER,
+\addtoindexx{abstract instance!example}
 which includes INNER, is shown in 
 Section \refersec{app:inliningexample2abstractinstance}.
 
 Note that the debugging information in this Figure differs from
 that in 
 Section \refersec{app:inliningexample1abstractinstance}
-in that INNER lacks a \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute
+in that INNER lacks a 
+\livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute
 and therefore is not a distinct abstract instance. INNER
 is merely an out\dash of\dash line routine that is part of OUTER’s
 abstract instance. This is reflected in the Figure 70 by
+\addtoindexx{abstract instance!example}
 the fact that the labels for INNER use the substring OUTER
 instead of INNER.
 
-A resulting concrete inlined instance of OUTER is shown in
-Section \refersec{app:inliningexample2concreteinstance}.
+A resulting 
+\addtoindexx{concrete instance!example}
+concrete inlined instance of OUTER is shown in
+Section \referfol{app:inliningexample2concreteinstance}.
 
 Notice in 
-Section \refersec{app:inliningexample2concreteinstance}.
+Section \referfol{app:inliningexample2concreteinstance}.
 that OUTER is expanded as a concrete
+\addtoindexx{concrete instance!example}
 inlined instance, and that INNER is nested within it as a
 concrete out\dash of\dash line subprogram. Because INNER is cloned
 for each inline expansion of OUTER, only the invariant
 attributes of INNER 
 (for example, \livelink{chap:DWATname}{DW\-\_AT\-\_name}) are specified
 in the abstract instance of OUTER, and the low\dash level,
+\addtoindexx{abstract instance!example}
 instance\dash specific attributes of INNER (for example,
-\livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}) are specified in each concrete instance of OUTER.
-
+\livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}) are specified in 
+each concrete instance of OUTER.
+\addtoindexx{concrete instance!example}
 The several calls of INNER within OUTER are compiled as normal
 calls to the instance of INNER that is specific to the same
 instance of OUTER that contains the calls.
@@ -1484,7 +1537,7 @@ instance of OUTER that contains the calls.
 \label{app:inliningexample2abstractinstance}
 \begin{alltt}
     ! Abstract instance for OUTER
-    !
+    ! \addtoindex{abstract instance}
 OUTER.AI.2.1:
     \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER")
@@ -1578,17 +1631,30 @@ OUTER.CI.2.6:
 
 In the third approach, one normal subprogram for INNER is
 compiled which is called from all concrete inlined instances of
+\addtoindexx{concrete instance!example}
+\addtoindexx{abstract instance!example}
 OUTER. The abstract instance for OUTER is shown in 
 Section \refersec{app:inliningexample3abstractinstance}.
 
 The most distinctive aspect of that Figure is that subprogram
 INNER exists only within the abstract instance of OUTER,
 and not in OUTER’s concrete instance. In the abstract
+\addtoindexx{concrete instance!example}
+\addtoindexx{abstract instance!example}
 instance of OUTER, the description of INNER has the full
 complement of attributes that would be expected for a
-normal subprogram. While attributes such as \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc},
-\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}, \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}, and so on, typically are omitted
-from an abstract instance because they are not invariant across
+normal subprogram. 
+While attributes such as 
+\livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc},
+\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}, 
+\livelink{chap:DWATlocation}{DW\-\_AT\-\_location},
+and so on, typically are omitted
+\addtoindexx{high PC attribute}
+from 
+\addtoindexx{low PC attribute}
+an 
+\addtoindexx{location attribute}
+abstract instance because they are not invariant across
 instances of the containing abstract instance, in this case
 those same attributes are included precisely because they are
 invariant -- there is only one subprogram INNER to be described
@@ -1604,13 +1670,17 @@ INNER at all; the representation of INNER does not vary across
 instances of OUTER and the abstract instance of OUTER includes
 the complete description of INNER, so that the description of
 INNER may be (and for reasons of space efficiency, should be)
-omitted from each concrete instance of OUTER.
+omitted from each 
+\addtoindexx{concrete instance!example}
+concrete instance of OUTER.
 
 There is one aspect of this approach that is problematical from
 the DWARF perspective. The single compiled instance of INNER
 is assumed to access up\dash level variables of OUTER; however,
 those variables may well occur at varying positions within
-the frames that contain the concrete inlined instances. A
+the frames that contain the 
+\addtoindexx{concrete instance!example}
+concrete inlined instances. A
 compiler might implement this in several ways, including the
 use of additional compiler generated parameters that provide
 reference parameters for the up\dash level variables, or a compiler
@@ -1634,7 +1704,7 @@ for accessing purposes.)
 \label{app:inliningexample3abstractinstance}
 \begin{alltt}
     ! Abstract instance for OUTER
-    !
+    ! \addtoindexx{abstract instance!example}
 OUTER.AI.3.1:
     \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER")
@@ -1681,7 +1751,7 @@ OUTER.AI.3.6:
 \label{app:inliningexample3concreteinstance}
 \begin{alltt}
     ! Concrete instance for call "OUTER(7)"
-    !
+    ! \addtoindexx{concrete instance!example}
 OUTER.CI.3.1:
     \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
         ! No name
@@ -1746,7 +1816,7 @@ Section \refersec{app:constantexpressionsdwarfdescription}.
             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("x")
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
       ! Concrete instance for square(9)
-      !
+      ! \addtoindexx{concrete instance!example}
 20\$: \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
         \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to 10\$)
         \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr}(present)
@@ -1772,8 +1842,8 @@ Section \refersec{app:constantexpressionsdwarfdescription}.
 
 \section{Unicode Character Example}
 \label{app:unicodecharacterexample}
-
-Unicode character encodings can be described in DWARF as
+\addtoindexx{Unicode|see {\textit{also} UTF-8}}
+\addtoindex{Unicode} character encodings can be described in DWARF as
 illustrated in 
 Section \refersec{app:unicodecharacterexamplesub}.
 
@@ -1812,7 +1882,9 @@ char32_t chr_b = U'h';
 \label{app:typesafeenumerationexample}
 
 
-C++ type\dash safe enumerations can be described in DWARF as illustrated in 
+C++ type\dash safe enumerations 
+\addtoindexx{type-safe enumeration}
+can be described in DWARF as illustrated in 
 Section \refersec{app:ctypesafeenumerationexample}.
 
 \begin{lstlisting}
@@ -1977,7 +2049,9 @@ wrapper<int>.
 \section{Template Alias Examples}
 \label{app:templatealiasexample}
 
-C++ template aliases can be described in DWARF as illustrated in 
+C++ template aliases can be described in DWARF as illustrated 
+\addtoindexx{template alias example}
+in 
 Section \refersec{app:templatealiasexample1}
 and 
 Section \refersec{app:templatealiasexample2}.
@@ -1997,6 +2071,7 @@ Beta<long> b;
 
 
 \subsection{template alias example 1}
+\addtoindexx{template alias example 1}
 \label{app:templatealiasexample1}
 \begin{alltt}
 ! DWARF representation for variable 'b'
@@ -2039,6 +2114,7 @@ X<Z<int>> z;
 
 
 \subsection{template alias example 2}
+\addtoindexx{template alias example 2}
 \label{app:templatealiasexample2}
 \begin{alltt}
 ! DWARF representation for X<Y<int>>