More pagination cleanups using \needspace and \needlines.
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
index f77d5fd..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.
 
@@ -779,41 +786,42 @@ 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}
@@ -845,18 +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
@@ -901,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: 
@@ -908,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"
@@ -953,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
@@ -992,6 +1017,11 @@ 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 
@@ -1019,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}
@@ -1066,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}
@@ -1110,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)
@@ -1157,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
@@ -1165,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}
   ...
@@ -1183,44 +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
@@ -1234,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
@@ -1253,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}
@@ -1302,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}.