More pagination cleanups using \needspace and \needlines.
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
index 23576b7..8bc8996 100644 (file)
@@ -76,7 +76,9 @@ contain sections as in:
 \end{alltt}
 
 followed (or preceded, the order is not significant) 
-by a series of section groups:
+by a series of 
+\addtoindexx{section group}
+section groups:
 \begin{alltt}
 ==== Section group 1
     \addtoindex{.debug\_info}
@@ -89,10 +91,12 @@ by a series of section groups:
     \addtoindex{.debug\_line}
 \end{alltt}
 
-where each section group might or might not contain executable
+where each \addtoindex{section group} might or might not contain executable
 code (\textit{.text} sections) or data (\textit{.data} sections).
 
-A \textit{section group} is a named set of section contributions
+\needlines{6}
+A \textit{\addtoindex{section group}} is a named set 
+of section contributions
 within an object file with the property that the entire set
 of section contributions must be retained or discarded as a
 whole; no partial elimination is allowed. Section groups can
@@ -100,30 +104,38 @@ generally be handled by a linker in two ways:
 
 \begin{enumerate}[1.]
 \item Given multiple identical (duplicate) section groups,
+\addtoindexx{section group}
 one of them is chosen to be kept and used, while the rest
 are discarded.
 
-\item Given a section group that is not referenced from any
-section outside of the section group, the section group
+\item Given a \addtoindex{section group} 
+that is not referenced from any
+section outside of the \addtoindex{section group}, 
+the section group
 is discarded.
 
-
 \end{enumerate}
 
 
-Which handling applies may be indicated by the section group
+Which handling applies may be indicated by the 
+\addtoindex{section group}
 itself and/or selection of certain linker options.
 
-For example, if a linker determines that section group 1
-from A.o and section group 3 from B.o are identical, it could
+For example, if a linker determines that 
+\addtoindex{section group} 1
+from A.o and 
+\addtoindex{section group} 3 from B.o are identical, it could
 discard one group and arrange that all references in A.o and
 B.o apply to the remaining one of the two identical section
 groups. This saves space.
 
-An important part of making it possible to “redirect”
-references to the surviving section group is the use of
+An important part of making it possible to \doublequote{redirect}
+references to the surviving 
+\addtoindex{section group} is the use of
 consistently chosen linker global symbols for referring to
-locations within each section group. It follows that references
+locations within each 
+\addtoindex{section group}.
+It follows that references
 are simply to external names and the linker already knows
 how to match up references and definitions.
 
@@ -141,20 +153,22 @@ compilation unit to another
 \item A means of having multiple contributions to specific sections
 (for example, \addtoindex{.debug\_info}, and so on) in a single object file.
 
-\item  A means of identifying a section group (giving it a name).
+\item  A means of identifying a \addtoindex{section group} (giving it a name).
 
 \item A means of identifying which sections go together to make
-up a section group, so that the group can be treated as a unit
+up a \addtoindex{section group}, 
+so that the group can be treated as a unit
 (kept or discarded).
 
-\item  A means of indicating how each section group should be
+\item  A means of indicating how each \addtoindex{section group} should be
 processed by the linker.
 
 \end{enumerate}
 
 \textit{The notion of section and section contribution used here
 corresponds closely to the similarly named concepts in the
-ELF object file representation. The notion of section group is
+ELF object file representation. 
+The notion of \addtoindex{section group} is
 an abstraction of common extensions of the ELF representation
 widely known as ``COMDATs'' or ``COMDAT sections''. (Other
 object file representations provide COMDAT\dash style mechanisms as
@@ -177,37 +191,39 @@ Implementations should clearly document their naming conventions.
 
 In the following, it will be helpful to refer to the examples
 in 
-Figure \refersec{app:duplicateeliminationexample1csource}
+Figure \ref{fig:duplicateeliminationexample1csource}
 through 
-Figure \refersec{app:duplicateeliminationexample2companiondwarf}
+Figure \ref{fig:duplicateeliminationexample2companiondwarf}
 of 
 Section \refersec{app:examples}.
 
 \textbf{Section Group Names}
 
-Section groups must have a section group name. For the subsequent 
+Section groups must have a \addtoindex{section group} name.
+\addtoindexx{section group!name}
+For the subsequent 
 \addtoindex{C++} example, a name like
-
-<producer-prefix>.<file-designator>.<gid-number>
-
+\begin{alltt}
+    <producer-prefix>.<file-designator>.<gid-number>
+\end{alltt}
 will suffice, where
 
-\begin{itemize}
+\begin{description}
 
-\item  \textless producer\dash prefix \textgreater 
+\item  [\textless producer\dash prefix\textgreater] 
 is some string specific to the
 producer, which has a language\dash designation embedded in the
 name when appropriate. (Alternatively, the language name
 could be embedded in the 
-\textless gid\dash number \textgreater).
+\textless gid\dash number\textgreater).
 
 
-\item  \textless file\dash designator \textgreater
+\item  [\textless file\dash designator\textgreater]
 names the file, such as wa.h in
 the example.
 
 
-\item  \textless gid\dash number \textgreater
+\item  [\textless gid\dash number\textgreater]
 is a string generated to identify the
 specific wa.h header file in such a way that
 
@@ -215,23 +231,26 @@ specific wa.h header file in such a way that
 
 \item  a 'matching' output from another compile generates
 the same 
-\textless gid\dash number \textgreater,
+\textless gid\dash number\textgreater,
 and
 
 \item  a non\dash matching output (say because of \#defines)
 generates a different 
-\textless gid\dash number \textgreater.
+\textless gid\dash number\textgreater.
 \end{itemize}
 
-\end{itemize}
+\end{description}
 
 \textit{It may be useful to think of a 
-\textless gid\dash number \textgreater
+\textless gid\dash number\textgreater
 as a kind
 of ``digital signature'' that allows a fast test for the
-equality of two section groups.}
+equality of two 
+\addtoindexx{section group}
+section groups.}
 
-So, for example, the section group corresponding to file wa.h
+So, for example, the \addtoindex{section group} 
+corresponding to file wa.h
 above is given the name \textit{my.compiler.company.cpp.wa.h.123456}.
 
 
@@ -241,7 +260,8 @@ above is given the name \textit{my.compiler.company.cpp.wa.h.123456}.
 Global labels for 
 \addtoindexx{debugging information entry!ownership relation}
 debugging information entries (need explained
-below) within a section group can be given names of the form
+below) within a \addtoindex{section group}
+can be given names of the form
 
 \begin{alltt}
     <prefix>.<file-designator>.<gid-number>.<die-number>
@@ -254,47 +274,50 @@ such as
 \end{alltt}
 
 where
-\begin{itemize}
-\item \textless prefix \textgreater\  
+\begin{description}
+\item [\textless prefix\textgreater]  
 distinguishes this as a DWARF debug info name, and should identify the producer
 and, when appropriate, the language.
-\item \textless file\dash designator\textgreater\  
+\item [\textless file\dash designator\textgreater]  
 and 
-\textless gid\dash number \textgreater
+\texttt{\textless gid\dash number\textgreater} 
 are as above.
 
-\item  \textless die\dash number \textgreater
+\item  [\textless die\dash number\textgreater]
 could be a number sequentially assigned 
 to entities (tokens, perhaps) found
 during compilation.
 
-\end{itemize}
+\end{description}
 
-In general, every point in the section group 
+In general, every point in the 
+\addtoindexx{section group}
+section group 
 \addtoindex{.debug\_info} that
-could be referenced from outside by any compilation unit must
+could be referenced from outside by \emph{any} compilation unit must
 normally have an external name generated for it in the linker
 symbol table, whether the current compilation references all
 those points or not.
 
-The completeness of the set of names generated is a
-quality\dash of\dash implementation issue.
+\textit{The completeness of the set of names generated is a
+quality\dash of\dash implementation issue.}
 
 It is up to the producer to ensure that if 
-<die-numbers>
-\textless die\dash numbers \textgreater
+\textless die\dash numbers\textgreater\ 
 in separate compilations would not match properly then a
 distinct 
-\textless gid\dash number \textgreater
+\textless gid\dash number\textgreater\ 
 is generated.
 
-Note that only section groups that are designated as
+Note that only 
+\addtoindexx{section group}
+section groups that are designated as
 duplicate\dash removal\dash applies actually require the
 \begin{alltt}
     <prefix>.<file-designator>.<gid-number>.<die-number>
 \end{alltt}
 external labels for debugging information entries as all other
-section group sections can use 'local' labels 
+\addtoindex{section group} sections can use 'local' labels 
 (section\dash relative
 relocations).
 
@@ -313,10 +336,11 @@ normally not usable and
 \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} is not necessary
 for a local label.)}
 
+% This should be a subsubsubsection header but that does work...
 \textbf{Use of \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} versus 
 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit}}
 
-A section group compilation unit that uses 
+A \addtoindex{section group} compilation unit that uses 
 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
 is like any other compilation unit, in that its contents
 are evaluated by consumers as though it were an ordinary
@@ -334,8 +358,11 @@ This also applies to \addtoindex{Fortran} INCLUDE lines when declarations
 are included into a procedure or module context.
 
 Consequently a compiler must use \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} (instead
-of \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}) in a section group whenever the section
-group contents are not necessarily globally visible. This
+of \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}) 
+in a \addtoindex{section group} 
+whenever the section group 
+contents are not necessarily globally visible. 
+This
 directs consumers to ignore that compilation unit when scanning
 top level declarations and definitions.
 
@@ -372,23 +399,23 @@ Use
 unit's debugging information entries to those of another
 compilation unit.
 
-When referencing into a removable section group 
+When referencing into a removable \addtoindex{section group}
 \addtoindex{.debug\_info}
 from another \addtoindex{.debug\_info} (from anywhere), the
-\begin{alltt}
-<prefix>.<file-designator>.<gid-number>.<die-number>
-\end{alltt}
+\texttt{<prefix>.<file-designator>.<gid-number>.<die-number>}
 name should be used for an external symbol and a relocation
 generated based on that name.
 
-When referencing into a non-section group 
+\textit{When referencing into a 
+\addtoindexx{section group}
+non-section group 
 \addtoindex{.debug\_info},
 from another \addtoindex{.debug\_info} (from anywhere) 
 \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} is
 still the form to be used, but a section\dash relative relocation
 generated by use of a non-exported name (often called an
 ``internal name'') may be used for references within the
-same object file.
+same object file.}
 
 \subsection{Examples}
 \label{app:examples}
@@ -402,7 +429,10 @@ In these examples, the focus is on the arrangement of DWARF
 information into sections (specifically the 
 \addtoindex{.debug\_info}
 section) and the naming conventions used to achieve references
-into section groups. In practice, all of the examples that
+into 
+\addtoindexx{section group}
+section groups. 
+In practice, all of the examples that
 follow involve DWARF sections other than just 
 \addtoindex{.debug\_info}
 (for example, \addtoindex{.debug\_line}, 
@@ -416,27 +446,22 @@ the underlying object language is not (and varies from system to system).
 
 \subsubsection{C++ Example}
 
-The addtoindex{C++} source 
+The \addtoindex{C++} source 
 \addtoindexx{DWARF duplicate elimination!C++ example}
 in 
-Section \refersec{app:duplicateeliminationexample1csource}
+Figure \refersec{fig:duplicateeliminationexample1csource}
 is used to illustrate the DWARF
 representation intended to allow duplicate elimination.
 
-\paragraph{Duplicate elimination example 1: C++ Source} 
-\label{app:duplicateeliminationexample1csource}
-
-File wa.h
-
-\begin{lstlisting}
+\begin{figure}[t]
+\textit{File wa.h}
+\begin{lstlisting}[numbers=none]
 struct A {
    int i;
 };
 \end{lstlisting}
-
-File wa.C
-
-\begin{lstlisting}
+\textit{File wa.c}
+\begin{lstlisting}[numbers=none]
 #include "wa.h";
 int
 f(A &a)
@@ -444,16 +469,16 @@ f(A &a)
     return a.i + 2;
 }
 \end{lstlisting}
+\caption{Duplicate elimination example \#1: C++ Source}
+\label{fig:duplicateeliminationexample1csource}
+\end{figure}
 
-
-section \refersec{app:duplicateeliminationexample1dwarfsectiongroup}
-shows the section group corresponding to the included file 
+Figure \refersec{fig:duplicateeliminationexample1dwarfsectiongroup}
+shows the \addtoindex{section group} corresponding to the included file 
 wa.h.
 
-
-\paragraph{Duplicate elimination example 1: DWARF section group} 
-
-\label{app:duplicateeliminationexample1dwarfsectiongroup}
+\begin{figure}
+\begin{dwflisting}
 % FIXME: the DWFORMrefn could use rethinking
 \begin{alltt}
 ==== Section group name:
@@ -477,15 +502,19 @@ DW.cpp.wa.h.123456.4: ! linker global symbol
             ! compact form \livetarg{chap:DWFORMrefn}{DW\-\_FORM\-\_refn} 
             ! for n 1,2,4, or 8 can be used)
 \end{alltt}
+\end{dwflisting}
+\caption{Duplicate elimination example \#1: DWARF section group} 
+\label{fig:duplicateeliminationexample1dwarfsectiongroup}
+\end{figure}
 
-
-Figure \refersec{app:duplicateeliminationexample1primarycompilationunit}
+Figure \refersec{fig:duplicateeliminationexample1primarycompilationunit}
 shows the ``normal'' DWARF sections, which are not part of
-any section group, and how they make use of the information
-in the section group shown above.
+any \addtoindex{section group}, 
+and how they make use of the information
+in the \addtoindex{section group} shown above.
 
-\paragraph{Duplicate elimination example 1: primary compilation unit} 
-\label{app:duplicateeliminationexample1primarycompilationunit}
+\begin{figure}
+\begin{dwflisting}
 \begin{alltt}
 == section .text
     [generated code for function f]
@@ -502,8 +531,12 @@ in the section group shown above.
                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to .L1)
         ...
 \end{alltt}
+\end{dwflisting}
+\caption{Duplicate elimination example \#1: primary compilation unit} 
+\label{fig:duplicateeliminationexample1primarycompilationunit}
+\end{figure}
 
-This example uses \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} for the section group,
+This example uses \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} for the \addtoindex{section group},
 implying that the contents of the compilation unit are
 globally visible (in accordance with 
 \addtoindex{C++} language rules).
@@ -515,41 +548,38 @@ globally visible (in accordance with
 For a \addtoindex{Fortran}
 \addtoindexx{DWARF duplicate elimination!Fortran example}
 example, consider 
-Figure \refersec{app:duplicateeliminationexample2fortransource}.
-
+Figure \refersec{fig:duplicateeliminationexample2fortransource}.
 
-\paragraph{Duplicate elimination example 2: Fortran source} 
-\label{app:duplicateeliminationexample2fortransource}
-
-File CommonStuff.fh
+\begin{figure}
+\textit{File CommonStuff.fh}
 \addtoindexx{Fortran}
-
-\begin{lstlisting}
+\begin{lstlisting}[numbers=none]
 IMPLICIT INTEGER(A-Z)
 COMMON /Common1/ C(100)
 PARAMETER(SEVEN = 7)
 \end{lstlisting}
 
-File Func.f
-\begin{lstlisting}
-
+\textit{File Func.f}
+\begin{lstlisting}[numbers=none]
 FUNCTION FOO (N)
 INCLUDE 'CommonStuff.fh'
 FOO = C(N + SEVEN)
 RETURN
 END
 \end{lstlisting}
+\caption{Duplicate elimination example \#2: Fortran source} 
+\label{fig:duplicateeliminationexample2fortransource}
+\end{figure}
 
 
-Section \refersec{app:duplicateeliminationexample2dwarfsectiongroup}
-shows the section group 
+Figure \refersec{fig:duplicateeliminationexample2dwarfsectiongroup}
+shows the \addtoindex{section group}
 corresponding to the included file 
 \addtoindexx{Fortran example}
 CommonStuff.fh.
 
-\paragraph{Duplicate elimination example 2: DWARF section group}
-\label{app:duplicateeliminationexample2dwarfsectiongroup}
-
+\begin{figure}
+\begin{dwflisting}
 \begin{alltt}
 ==== Section group name:
 
@@ -590,14 +620,16 @@ DW.myf90.CommonStuff.fh.654321.4: ! linker global symbol
             ! base type INTEGER
         \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}(constant 7)
 \end{alltt}
+\end{dwflisting}
+\caption{Duplicate elimination example \#2: DWARF section group}
+\label{fig:duplicateeliminationexample2dwarfsectiongroup}
+\end{figure}
 
-Section \refersec{app:duplicateeliminationexample2primaryunit}
+Figure \refersec{fig:duplicateeliminationexample2primaryunit}
 shows the sections for the primary compilation unit.
 
-
-
-\paragraph{Duplicate elimination example 2: primary unit }
-\label{app:duplicateeliminationexample2primaryunit}
+\begin{figure}
+\begin{dwflisting}
 \begin{alltt}
 == section .text
     [code for function Foo]
@@ -619,33 +651,37 @@ shows the sections for the primary compilation unit.
                     \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to DW.f90.F90\$main.f.2)
                         ! base type INTEGER
 \end{alltt}
+\end{dwflisting}
+\caption{Duplicate elimination example \#2: primary unit}
+\label{fig:duplicateeliminationexample2primaryunit}
+\end{figure}
 
 A companion main program is shown in 
-Section \refersec{app:duplicateeliminationexample2companionsource}
-
-\paragraph{Duplicate elimination example 2: companion source }
-\label{app:duplicateeliminationexample2companionsource}
+Figure \refersec{fig:duplicateeliminationexample2companionsource}
 
-File Main.f 
-
-\begin{lstlisting}
+\begin{figure}
+\textit{File Main.f} 
+\begin{lstlisting}[numbers=none]
 INCLUDE 'CommonStuff.fh'
 C(50) = 8
 PRINT *, 'Result = ', FOO(50 - SEVEN)
 END
 \end{lstlisting}
+\caption{Duplicate elimination example \#2: companion source }
+\label{fig:duplicateeliminationexample2companionsource}
+\end{figure}
 
+\needlines{3}
 That main program results in an object file that
-contained a duplicate of the section group named
+contained a duplicate of the \addtoindex{section group} named
 my.f90.company.f90.CommonStuff.fh.654321 
 corresponding to the
 included file as well as the remainder of the main subprogram
 as shown in 
-Section \refersec{app:duplicateeliminationexample2companiondwarf}.
-
-\paragraph{Duplicate elimination example 2: companion DWARF }
-\label{app:duplicateeliminationexample2companiondwarf}
+Figure \refersec{fig:duplicateeliminationexample2companiondwarf}.
 
+\begin{figure}
+\begin{dwflisting}
 \begin{alltt}
 == section \addtoindex{.debug\_info}
     \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
@@ -668,13 +704,17 @@ Section \refersec{app:duplicateeliminationexample2companiondwarf}.
                     DW.myf90.CommonStuff.fh.654321.3)
             ...
 \end{alltt}
+\end{dwflisting}
+\caption{Duplicate elimination example \#2: companion DWARF }
+\label{fig:duplicateeliminationexample2companiondwarf}
+\end{figure}
 
-
-This example uses \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} for the section group
+This example uses \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} for the \addtoindex{section group}
 because the included declarations are not independently
 visible as global entities.
 
 
+\needlines{6}
 \subsubsection{C Example}
 
 The \addtoindex{C} example 
@@ -683,14 +723,14 @@ in this Section might appear to be equally
 valid as a \addtoindex{C} example. However, it is prudent to include
 a \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit}
 in the primary unit 
-(see Figure \refersec{app:duplicateeliminationexample1primarycompilationunit})
+(see Figure \refersec{fig:duplicateeliminationexample1primarycompilationunit})
 with an \livelink{chap:DWATimport}{DW\-\_AT\-\_import} attribute that refers to the proper unit
-in the section group.
+in the \addtoindex{section group}.
 
 \textit{The \addtoindex{C} rules for consistency of global (file scope) symbols
 across compilations are less strict than for C++; inclusion
 of the import unit attribute assures that the declarations of
-the proper section group are considered before declarations
+the proper \addtoindex{section group} are considered before declarations
 from other compilations.}
 
 
@@ -701,7 +741,7 @@ A large portion of debug information is type information, and
 in a typical compilation environment, many types are duplicated
 many times. One method of controlling the amount of duplication
 is separating each type into a separate 
-addtoindex{.debug\_types} section
+\addtoindex{.debug\_types} section
 and arranging for the linker to recognize and eliminate
 duplicates at the individual type level.
 
@@ -731,52 +771,57 @@ many
 linkers today support the concept of a COMDAT group or
 linkonce section. The general idea is that a ``key'' can be
 attached to a section or a group of sections, and the linker
-will include only one copy of a section group (or individual
-section) for any given key. For 
+will include only one copy of a \addtoindex{section group}
+(or individual section) for any given key. 
+For 
 \addtoindex{.debug\_types} sections, the
-key is the type signature formed from the algorithm given in
+key is the \addtoindex{type signature}
+formed from the algorithm given in
 Section \refersec{datarep:typesignaturecomputation}.
 
 \subsection{Signature Computation Example}
 \label{app:signaturecomputationexample}
 
-As an example, consider a \addtoindex{C++} header file 
+As an example, 
+\addtoindexx{type signature!example computation}
+consider a \addtoindex{C++} header file 
 containing the type definitions shown
-in Section \refersec{app:typesignatureexamplescsource}.
+in Figure \refersec{fig:typesignatureexamplescsource}.
 
-\subsubsection{ Type signature examples: C++ source}
-\label{app:typesignatureexamplescsource}
+\begin{figure}
 \begin{lstlisting}
 namespace N {
 
- struct B;
-
- struct C {
-     int x;
-     int y;
- };
-
- class A {
-   public:
-     A(int v);
-     int v();
-   private:
-     int v_;
-     struct A *next;
-     struct B *bp;
-     struct C c;
- };
-
- }
+    struct B;
+
+    struct C {
+        int x;
+        int y;
+    };
+
+    class A {
+    public:
+        A(int v);
+        int v();
+    private:
+        int v_;
+        struct A *next;
+        struct B *bp;
+        struct C c;
+    };
+}
 \end{lstlisting}
+\caption{Type signature examples: C++ source}
+\label{fig:typesignatureexamplescsource}
+\end{figure}
 
 Next, consider one possible representation of the DWARF
-information that describes the type “struct C” as shown
+information that describes the type \doublequote{struct C} as shown
 in 
-\refersec{app:typesignaturecomputation1dwarfrepresentation}:
+\refersec{fig:typesignaturecomputation1dwarfrepresentation}:
 
-\subsubsection{Type signature  computation 1: DWARF representation}
-\label{app:typesignaturecomputation1dwarfrepresentation}
+\begin{figure}
+\begin{dwflisting}
 % We keep the : (colon) away from the attribute so tokenizing in the python tools
 % does not result in adding : into the attribute name.
 \begin{alltt}
@@ -808,17 +853,22 @@ L2:
          \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding} : \livelink{chap:DWATEsigned}{DW\-\_ATE\-\_signed}
          \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "int"
 \end{alltt}
+\end{dwflisting}
+\caption{Type signature computation \#1: DWARF representation}
+\label{fig:typesignaturecomputation1dwarfrepresentation}
+\end{figure}
 
+\needlines{3}
 In computing a signature for the type N::C, flatten the type
+\addtoindexx{type signature}
 description into a byte stream according to the procedure
 outlined in 
 Section \refersec{datarep:typesignaturecomputation}.
 The result is shown in 
-Section \refersec{app:typesignaturecomputation1flattenedbytestream}.
-
-\subsubsection{Type signature  computation 1: flattened byte stream}
-\label{app:typesignaturecomputation1flattenedbytestream}
+Figure \refersec{fig:typesignaturecomputation1flattenedbytestream}.
 
+\begin{figure}
+\begin{dwflisting}
 \begin{alltt}
 // Step 2: 'C' \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} "N"
 0x43 0x39 0x4e 0x00
@@ -863,24 +913,27 @@ Section \refersec{app:typesignaturecomputation1flattenedbytestream}.
 // Step 7: End of \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} "C"
 0x00
 \end{alltt}
+\end{dwflisting}
+\caption{Type signature computation \#1: flattened byte stream}
+\label{fig:typesignaturecomputation1flattenedbytestream}
+\end{figure}
 
-Running an MD5 hash over this byte stream, and taking the
+Running an \addtoindex{MD5 hash} over this byte stream, and taking the
 low\dash order 64 bits, yields the final signature: 
 0xd28081e8 dcf5070a.
 
 Next, consider a representation of the DWARF information that
 describes the type ``class A'' as shown in 
-Section \refersec{app:typesignaturecomputation2dwarfrepresentation}.
-
-
-\subsubsection{Type signature  computation 2: DWARF representation}
-\label{app:typesignaturecomputation2dwarfrepresentation}
+Figure \refersec{fig:typesignaturecomputation2dwarfrepresentation}.
 
+\begin{figure}
+\figurepart{1}{2}
+\begin{dwflisting}
 \begin{alltt}
   \livelink{chap:DWTAGtypeunit}{DW\-\_TAG\-\_type\-\_unit}
       \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language} : \livelink{chap:DWLANGCplusplus}{DW\-\_LANG\-\_C\-\_plus\-\_plus} (4)
     \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
-          \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "N"
+        \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "N"
 L1:
         \livelink{chap:DWTAGclasstype}{DW\-\_TAG\-\_class\-\_type}
              \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "A"
@@ -915,7 +968,17 @@ L1:
                \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : 0xd28081e8 dcf5070a (signature for struct C)
                \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} : 12
                \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} : \livelink{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}
-       \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
+\end{alltt}
+\end{dwflisting}
+\caption{Type signature computation \#2: DWARF representation}
+\label{fig:typesignaturecomputation2dwarfrepresentation}
+\end{figure}
+
+\begin{figure}
+\figurepart{2}{2}
+\begin{dwflisting}
+\begin{alltt}
+      \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
            \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} : 1
            \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "A"
            \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
@@ -954,20 +1017,31 @@ L5:
            \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "B"
            \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} : 1
 \end{alltt}
+\end{dwflisting}
+\begin{center}
+Figure~\ref{fig:typesignaturecomputation2dwarfrepresentation} Type signature computation \#2: DWARF representation \textit{(concluded)}
+\end{center}
+\end{figure}
 
 In this example, the structure types N::A and N::C have each
-been placed in separate type units.  For N::A, the actual
+been placed in separate 
+\addtoindexx{type unit}
+type units.  For N::A, the actual
 definition of the type begins at label L1. The definition
 involves references to the int base type and to two pointer
 types. The information for each of these referenced types is
-also included in this type unit, since base types and pointer
+also included in this \addtoindex{type unit}, 
+since base types and pointer
 types are trivial types that are not worth the overhead of a
-separate type unit. The last pointer type contains a reference
+separate \addtoindex{type unit}. 
+The last pointer type contains a reference
 to an incomplete type N::B, which is also included here as
 a declaration, since the complete type is unknown and its
 signature is therefore unavailable. There is also a reference
 to N::C, using 
-\livelink{chap:DWFORMrefsig8}{DW\-\_FORM\-\_ref\-\_sig8} to refer to the type signature
+\livelink{chap:DWFORMrefsig8}{DW\-\_FORM\-\_ref\-\_sig8} to 
+refer to the type signature
+\addtoindexx{type signature}
 for that type.
 
 In computing a signature for the type N::A, flatten the type
@@ -975,10 +1049,11 @@ description into a byte stream according to the procedure
 outlined in 
 Section \refersec{datarep:typesignaturecomputation}.
 The result is shown in 
-Section \refersec{app:typesignatureexample2flattenedbytestream}.
+Figure \refersec{fig:typesignatureexample2flattenedbytestream}.
 
-\subsubsection{Type signature example 2: flattenedbytestream}
-\label{app:typesignatureexample2flattenedbytestream}
+\begin{figure}
+\figurepart{1}{3}
+\begin{dwflisting}
 % DWARF4 had a \livelink{chap:DWATnamespace}{DW_AT_namespace} below, 
 % but this error is fixed here to be \livelink{chap:DWTAGnamespace}{DW_TAG_namespace}.
 \begin{alltt}
@@ -1022,6 +1097,16 @@ Section \refersec{app:typesignatureexample2flattenedbytestream}.
     0x41 0x32 0x0d 0x03
     // Step 4: 'A' \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 4
     0x41 0x38 0x0d 0x04
+\end{alltt}
+\end{dwflisting}
+\caption{Type signature example \#2: flattened byte stream}
+\label{fig:typesignatureexample2flattenedbytestream}
+\end{figure}
+
+\begin{figure}
+\figurepart{2}{3}
+\begin{dwflisting}
+\begin{alltt}    
     // Step 6: 'T' \livelink{chap:DWATtype}{DW\-\_AT\-\_type} (type \#3)
     0x54 0x49
         // Step 3: 'D' \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}
@@ -1066,6 +1151,17 @@ Section \refersec{app:typesignatureexample2flattenedbytestream}.
     0x41 0x03 0x08 0x63 0x00
     // Step 4: 'A' \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} \livelink{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}
     0x41 0x32 0x0d 0x03
+\end{alltt}
+\end{dwflisting}
+\begin{center}
+Figure~\ref{fig:typesignatureexample2flattenedbytestream} Type signature example \#2: flattened byte stream \textit{(continued)}
+\end{center}
+\end{figure}
+    
+\begin{figure}
+\figurepart{3}{3}
+\begin{dwflisting}
+\begin{alltt}
     // Step 4: 'A' \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 12
     0x41 0x38 0x0d 0x0c
     // Step 6: 'T' \livelink{chap:DWATtype}{DW\-\_AT\-\_type} (type \#5)
@@ -1113,21 +1209,24 @@ Section \refersec{app:typesignatureexample2flattenedbytestream}.
 // Step 7: End of \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} "A"
 0x00
 \end{alltt}
+\end{dwflisting}
+\begin{center}
+Figure~\ref{fig:typesignatureexample2flattenedbytestream} Type signature example \#2: flattened byte stream \textit{(concluded)}
+\end{center}
+\end{figure}
 
-Running an MD5 hash over this byte stream, and taking the
+Running an \addtoindex{MD5 hash} over this byte stream, and taking the
 low-order 64 bits, yields the final signature: 0xd6d160f5
 5589f6e9.
 
 
 A source file that includes this header file may declare a
 variable of type N::A, and its DWARF information may look
-that shown in 
-Section \refersec{app:typesignatureexampleusage}.
-
-
-\subsubsection{Type signature example usage}
-\label{app:typesignatureexampleusage}
+like that shown in 
+Figure \refersec{fig:typesignatureexampleusage}.
 
+\begin{figure}
+\begin{dwflisting}
 \begin{alltt}
   \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
   ...
@@ -1139,43 +1238,43 @@ Section \refersec{app:typesignatureexampleusage}.
       \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} : ...
     ...
 \end{alltt}
+\end{dwflisting}
+\caption{Type signature example usage}
+\label{fig:typesignatureexampleusage}
+\end{figure}
 
 \subsection{Type Signature Computation Grammar}
 \label{app:typesignaturecomputationgrammar}
 
-This section
+Figure \refersec{fig:typesignaturecomputationgrammar}
+\addtoindexx{type signature!computation grammar}
 presents a semi-formal grammar that may aid in understanding
 how the bytes of the flattened type description are formed
-during the type signature computation algorithm of Section
+during the type signature computation algorithm of
 Section \refersec{datarep:typesignaturecomputation}. 
 
+\begin{figure}[h]
+\begin{dwflisting}
 %FIXME: The index entries here with \addtoindexx are ineffective.
 \begin{alltt}
 signature
     : opt-context debug-entry attributes children
-
 opt-context           // Step 2
     : 'C' tag-code string opt-context
     : empty
-
 debug-entry           // Step 3
     : 'D' tag-code
-
 attributes            // Steps 4, 5, 6
     : attribute attributes
     : empty
-
 attribute
     : 'A' at-code form-encoded-value     // Normal attributes
-    : 'N' at-code opt-context 'E' string // Reference to type
-                                         // by name
-    : 'R' at-code back-ref               // Back-reference 
-                                         // to visited type
+    : 'N' at-code opt-context 'E' string // Reference to type by name
+    : 'R' at-code back-ref               // Back-reference to visited type
     : 'T' at-code signature              // Recursive type
 children             //  Step 7
     : child children
-    : '\\0'
-
+    : '0'
 child
     : 'S' tag-code string
     : signature
@@ -1189,18 +1288,17 @@ form-encoded-value
     : \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} string \addtoindexx{string class}
     : \livelink{chap:DWFORMblock}{DW\-\_FORM\-\_block} \nolink{block} \addtoindexx{block class}
 \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} \addtoindexx{string class}
-    : '\\x08'
+    : 'x08'
 \livelink{chap:DWFORMblock}{DW\-\_FORM\-\_block}  \addtoindexx{block class}
-    : '\\x09'
+    : 'x09'
 \livelink{chap:DWFORMflag}{DW\-\_FORM\-\_flag} \addtoindexx{flag class}
-    : '\\x0c'
+    : 'x0c'
 \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} \addtoindexx{constant class}
-    : '\\x0d'
+    : 'x0d'
 value
     : <SLEB128>
 \nolink{block}
-    : <ULEB128> <fixed-length-block>
-                      // The ULEB128 gives the length of the \nolink{block}
+    : <ULEB128> <fixed-length-block> // The ULEB128 gives the length of the \nolink{block}
 back-ref
     : <ULEB128>
 string
@@ -1208,7 +1306,10 @@ string
 empty
     :
 \end{alltt}
-
+\end{dwflisting}
+\caption{Type signature computation grammar}
+\label{fig:typesignaturecomputationgrammar}
+\end{figure}
 
 \section{Summary of Compression Techniques}
 \label{app:summaryofcompressiontechniques}
@@ -1224,11 +1325,13 @@ there is substantial header file information
 duplication.
 
 A reasonable approach is to put each header file in its own
-section group, using the naming rules mentioned above. The
+\addtoindex{section group}, using the naming rules mentioned above. The
 section groups are marked to ensure duplicate removal.
 
 All data instances and code instances (even if they came
-from the header files above) are put into non-section group
+from the header files above) are put 
+\addtoindexx{section group}
+into non-section group
 sections such as the base object file 
 \addtoindex{.debug\_info} section.
 
@@ -1245,23 +1348,19 @@ this function, should be reduced to just a single copy.
 For each such code group (function template in this example)
 the compiler assigns a name for the group which will match
 all other instantiations of this function but match nothing
-else. The section groups are marked to ensure duplicate
+else. 
+The 
+\addtoindexx{section group}
+section groups are marked to ensure duplicate
 removal, so that the second and subsequent definitions seen
 by the static linker are simply discarded.
 
 
 References to other 
 \addtoindex{.debug\_info} sections follow the approach
-suggested above, but the naming rule might be slightly
-different in that the 
-\begin{alltt}
-<file-designator> 
-\end{alltt}
-should be interpreted
-as a 
-\begin{alltt}
-<function-designator>.
-\end{alltt}
+suggested above, but the naming rule is slightly
+different in that the \texttt{\textless file-designator\textgreater} 
+should be interpreted as a \texttt{\textless file-designator\textgreater}.
 
 
 
@@ -1271,7 +1370,9 @@ as a
 Section groups can help make it easy for a linker to completely
 remove unused functions.
 
-Such section groups are not marked for duplicate removal,
+Such 
+\addtoindexx{section group}
+section groups are not marked for duplicate removal,
 since the functions are not duplicates of anything.
 
 Each function is given a compilation unit and a section
@@ -1286,7 +1387,9 @@ file\dash level compilation unit using \livelink{chap:DWTAGimportedunit}{DW\-\_T
 
 Section groups can use \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} and internal labels
 (section\dash relative relocations) to refer to the main object
-file sections, as the section groups here are either deleted
+file sections, as the 
+\addtoindexx{section group}
+section groups here are either deleted
 as unused or kept. There is no possibility (aside from error)
 of a group from some other compilation being used in place
 of one of these groups.
@@ -1299,7 +1402,10 @@ Abstract instances
 \addtoindexx{abstract instance}
 \addtoindexx{concrete out-of-line instance}
 and concrete-out-of-line instances may be
-put in distinct compilation units using section groups. This
+put in distinct compilation units using 
+\addtoindexx{section group}
+section groups. 
+This
 makes possible some useful duplicate DWARF elimination.
 
 \textit{No special provision for eliminating class duplication
@@ -1312,6 +1418,7 @@ groups.}
 \label{app:separatetypeunits}
 
 Each complete declaration of a globally-visible type can be
+\addtoindexx{type unit}
 placed in its own separate type section, with a group key
 derived from the type signature. The linker can then remove
 all duplicate type declarations based on the key.