Misc corrections Chpt 6 thru App A
[dwarf-doc.git] / dwarf5 / latexdoc / examples.tex
index 4f3ae06..c3b1954 100644 (file)
@@ -165,9 +165,9 @@ using DWARF.
 
 \subsection{Fortran 90 Example}
 \label{app:fortran90example}
-Consider the Fortran 90 source fragment in 
+Consider the \addtoindex{Fortran 90} source fragment in 
 \addtoindexx{array type entry!examples}
-Figure \refersec{fig:fortran90examplesourcefragment}.
+Figure \referfol{fig:fortran90examplesourcefragment}.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -185,7 +185,9 @@ 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
@@ -199,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}
@@ -221,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}
 
 
@@ -258,7 +263,7 @@ object will not have a
 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}
@@ -286,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}
@@ -389,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:
 
@@ -493,7 +502,7 @@ would be different.
 \subsection{Ada Example}
 \label{app:adaexample}
 
-Figure \refersec{fig:adaexamplesourcefragment}
+Figure \referfol{fig:adaexamplesourcefragment}
 illustrates two kinds of \addtoindex{Ada} 
 parameterized array, one embedded in a record.
 
@@ -510,7 +519,8 @@ 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
@@ -618,10 +628,11 @@ of this example and therefore not shown.
 \subsection{Pascal Example}
 \label{app:pascalexample}
 
-The Pascal source in 
-Figure \refersec{fig:packedrecordexamplesourcefragment}
+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
@@ -637,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 
@@ -705,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}
@@ -744,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}
@@ -836,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}
@@ -848,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}
 
 
@@ -885,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
             ...
@@ -906,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
              ...
@@ -936,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}
@@ -960,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}
@@ -977,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
@@ -987,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
@@ -1007,7 +1033,7 @@ SPECIAL(1, 7)&0x73 & \\
 \end{centering}
 
 
-Table \refersec{tab:linenumberprogramexamplealternateencoding}
+Table \referfol{tab:linenumberprogramexamplealternateencoding}
 shows an alternate 
 encoding of the same program using 
 standard opcodes to advance
@@ -1017,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
@@ -1078,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 >
@@ -1105,15 +1131,15 @@ 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
 \addtoindex{.debug\_frame} section are shown in 
 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
@@ -1133,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
@@ -1161,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
@@ -1251,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
@@ -1276,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}
 
 
@@ -1481,10 +1511,10 @@ instead of INNER.
 A resulting 
 \addtoindexx{concrete instance!example}
 concrete inlined instance of OUTER is shown in
-Section \refersec{app:inliningexample2concreteinstance}.
+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
@@ -1495,7 +1525,6 @@ attributes of INNER
 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.
 \addtoindexx{concrete instance!example}
@@ -1614,9 +1643,18 @@ and not in OUTER’s concrete instance. In the abstract
 \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
@@ -1804,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}.
 
@@ -1844,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}
@@ -2009,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}.
@@ -2029,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'
@@ -2071,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>>