More pagination cleanups using \needspace and \needlines.
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
index c7c76c9..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
@@ -128,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
@@ -190,9 +191,9 @@ Implementations should clearly document their naming conventions.
 
 In the following, it will be helpful to refer to the examples
 in 
-Figure \ref{app:duplicateeliminationexample1csource}
+Figure \ref{fig:duplicateeliminationexample1csource}
 through 
-Figure \ref{app:duplicateeliminationexample2companiondwarf}
+Figure \ref{fig:duplicateeliminationexample2companiondwarf}
 of 
 Section \refersec{app:examples}.
 
@@ -214,7 +215,7 @@ 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]
@@ -293,13 +294,13 @@ 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 
 \textless die\dash numbers\textgreater\ 
@@ -405,7 +406,7 @@ from another \addtoindex{.debug\_info} (from anywhere), the
 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},
@@ -414,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}
@@ -453,13 +454,13 @@ is used to illustrate the DWARF
 representation intended to allow duplicate elimination.
 
 \begin{figure}[t]
-\textbf{File wa.h:}
+\textit{File wa.h}
 \begin{lstlisting}[numbers=none]
 struct A {
    int i;
 };
 \end{lstlisting}
-\textbf{File wa.c:}
+\textit{File wa.c}
 \begin{lstlisting}[numbers=none]
 #include "wa.h";
 int
@@ -502,7 +503,7 @@ DW.cpp.wa.h.123456.4: ! linker global symbol
             ! for n 1,2,4, or 8 can be used)
 \end{alltt}
 \end{dwflisting}
-\caption{Duplicate elimination example 1: DWARF section group} 
+\caption{Duplicate elimination example \#1: DWARF section group} 
 \label{fig:duplicateeliminationexample1dwarfsectiongroup}
 \end{figure}
 
@@ -550,7 +551,7 @@ example, consider
 Figure \refersec{fig:duplicateeliminationexample2fortransource}.
 
 \begin{figure}
-\textbf{File CommonStuff.fh}
+\textit{File CommonStuff.fh}
 \addtoindexx{Fortran}
 \begin{lstlisting}[numbers=none]
 IMPLICIT INTEGER(A-Z)
@@ -558,7 +559,7 @@ COMMON /Common1/ C(100)
 PARAMETER(SEVEN = 7)
 \end{lstlisting}
 
-\textbf{File Func.f}
+\textit{File Func.f}
 \begin{lstlisting}[numbers=none]
 FUNCTION FOO (N)
 INCLUDE 'CommonStuff.fh'
@@ -620,7 +621,7 @@ DW.myf90.CommonStuff.fh.654321.4: ! linker global symbol
         \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}(constant 7)
 \end{alltt}
 \end{dwflisting}
-\caption{Duplicate elimination example 2: DWARF section group}
+\caption{Duplicate elimination example \#2: DWARF section group}
 \label{fig:duplicateeliminationexample2dwarfsectiongroup}
 \end{figure}
 
@@ -659,7 +660,7 @@ A companion main program is shown in
 Figure \refersec{fig:duplicateeliminationexample2companionsource}
 
 \begin{figure}
-\textbf{File Main.f:
+\textit{File Main.f
 \begin{lstlisting}[numbers=none]
 INCLUDE 'CommonStuff.fh'
 C(50) = 8
@@ -670,6 +671,7 @@ END
 \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 
@@ -703,7 +705,7 @@ Figure \refersec{fig:duplicateeliminationexample2companiondwarf}.
             ...
 \end{alltt}
 \end{dwflisting}
-\caption{Duplicate elimination example 2: companion DWARF }
+\caption{Duplicate elimination example \#2: companion DWARF }
 \label{fig:duplicateeliminationexample2companiondwarf}
 \end{figure}
 
@@ -712,6 +714,7 @@ because the included declarations are not independently
 visible as global entities.
 
 
+\needlines{6}
 \subsubsection{C Example}
 
 The \addtoindex{C} example 
@@ -813,7 +816,7 @@ namespace N {
 \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{fig:typesignaturecomputation1dwarfrepresentation}:
 
@@ -855,6 +858,7 @@ L2:
 \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
@@ -1242,51 +1246,42 @@ Figure \refersec{fig:typesignatureexampleusage}.
 \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'
-
 child
     : 'S' tag-code string
     : signature
-
 tag-code
     : <ULEB128>
-
 at-code
     : <ULEB128>
-    
 form-encoded-value
     : \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} value \addtoindexx{constant class}
     : \livelink{chap:DWFORMflag}{DW\-\_FORM\-\_flag} value \addtoindexx{flag class}
@@ -1300,23 +1295,21 @@ form-encoded-value
     : 'x0c'
 \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} \addtoindexx{constant class}
     : '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
     : <null-terminated-string>
-    
 empty
     :
 \end{alltt}
-
+\end{dwflisting}
+\caption{Type signature computation grammar}
+\label{fig:typesignaturecomputationgrammar}
+\end{figure}
 
 \section{Summary of Compression Techniques}
 \label{app:summaryofcompressiontechniques}
@@ -1365,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}.