More pagination cleanups using \needspace and \needlines.
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
index 2e2cf5c..8bc8996 100644 (file)
@@ -94,6 +94,7 @@ section groups:
 where each \addtoindex{section group} might or might not contain executable
 code (\textit{.text} sections) or data (\textit{.data} sections).
 
+\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
@@ -113,7 +114,6 @@ section outside of the \addtoindex{section group},
 the section group
 is discarded.
 
-
 \end{enumerate}
 
 
@@ -129,7 +129,7 @@ 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”
+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
@@ -191,9 +191,9 @@ 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}.
 
@@ -203,27 +203,27 @@ 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
 
@@ -231,18 +231,18 @@ 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 
@@ -274,40 +274,39 @@ 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 
 \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 
@@ -337,6 +336,7 @@ 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}}
 
@@ -402,13 +402,11 @@ compilation unit.
 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 
+\textit{When referencing into a 
 \addtoindexx{section group}
 non-section group 
 \addtoindex{.debug\_info},
@@ -417,7 +415,7 @@ from another \addtoindex{.debug\_info} (from anywhere)
 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}
@@ -448,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)
@@ -476,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}
+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:
@@ -509,16 +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 \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]
@@ -535,6 +531,10 @@ in the \addtoindex{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 \addtoindex{section group},
 implying that the contents of the compilation unit are
@@ -548,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}
+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:
 
@@ -623,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]
@@ -652,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 \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}
@@ -701,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 \addtoindex{section group}
 because the included declarations are not independently
 visible as global entities.
 
 
+\needlines{6}
 \subsubsection{C Example}
 
 The \addtoindex{C} example 
@@ -716,7 +723,7 @@ 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 \addtoindex{section group}.
 
@@ -734,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.
 
@@ -768,49 +775,53 @@ 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}
@@ -842,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
@@ -897,6 +913,10 @@ 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 \addtoindex{MD5 hash} over this byte stream, and taking the
 low\dash order 64 bits, yields the final signature: 
@@ -904,17 +924,16 @@ low\dash order 64 bits, yields the final signature:
 
 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"
@@ -949,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
@@ -988,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
@@ -1009,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}
@@ -1056,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}
@@ -1100,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)
@@ -1147,6 +1209,11 @@ 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 \addtoindex{MD5 hash} over this byte stream, and taking the
 low-order 64 bits, yields the final signature: 0xd6d160f5
@@ -1155,13 +1222,11 @@ low-order 64 bits, yields the final signature: 0xd6d160f5
 
 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}
   ...
@@ -1173,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
@@ -1223,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
@@ -1242,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}
@@ -1291,16 +1358,9 @@ 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}.
 
 
 
@@ -1358,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.