Merge branch 'HEAD' of dwarfgit@dwarfstd.org:dwarf-doc.git
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
index 7a07e7d..1aec7b6 100644 (file)
@@ -1,5 +1,5 @@
 \chapter[Compression (Informative)]{DWARF Compression and Duplicate Elimination (Informative)}
-\label{dwarfcompressionandduplicateeliminationinformative}
+\label{app:dwarfcompressionandduplicateeliminationinformative}
 
 % It seemed difficult to get close to the same layout and 
 % captioning as DWARF4 here with figures as they moved (floated)
@@ -51,7 +51,7 @@ but aside from the DWARF sections, the names are just meant
 to suggest traditional contents as a way of explaining the
 approach, not to be limiting.}
 
-A traditional relocatable object output 
+A traditional relocatable object output file
 from a single compilation might contain sections 
 named:
 \begin{alltt}
@@ -62,7 +62,7 @@ named:
     \dotdebugline{}
     \dotdebugaranges{}
 \end{alltt}
-A relocatable object from a compilation system 
+A relocatable object file from a compilation system 
 attempting duplicate DWARF elimination might
 contain sections as in:
 
@@ -144,23 +144,22 @@ linker (outside of DWARF itself, and normal object/linker
 facilities such as simple relocations) are:
 \begin{enumerate}[1. ]
 
-\item A means of referencing from inside one \dotdebuginfo{}
-compilation unit to another 
-\dotdebuginfo{} compilation unit
-(\DWFORMrefaddr{} provides this).
+\item A means to reference the \dotdebuginfo{} information 
+of one compilation unit from the \dotdebuginfo{} section of 
+another compilation unit (\DWFORMrefaddr{} provides this).
 
-\item A means of having multiple contributions to specific sections
-(for example, \dotdebuginfo{}, and so on) in a single object file.
+\item A means to combine multiple contributions to specific sections
+(for example, \dotdebuginfo{}) into a single object file.
 
-\item  A means of identifying a \addtoindex{section group} (giving it a name).
+\item  A means to identify a \addtoindex{section group} 
+(giving it a name).
 
-\item A means of identifying which sections go together to make
-up a \addtoindex{section group}, 
-so that the group can be treated as a unit
-(kept or discarded).
+\item A means to indicate which sections go together to make
+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 \addtoindex{section group} should be
-processed by the linker.
+\item  A means to indicate how each \addtoindex{section group} 
+should be processed by the linker.
 
 \end{enumerate}
 
@@ -234,7 +233,7 @@ the same
 \textless gid\dash number\textgreater,
 and
 
-\item  a non\dash matching output (say because of \texttt{\#defines})
+\item  a non-matching output (say because of \texttt{\#defines})
 generates a different 
 \textless gid\dash number\textgreater.
 \end{itemize}
@@ -259,7 +258,7 @@ above is given the name \texttt{my.compiler.company.cpp.wa.h.123456}.
 
 Global labels for 
 \addtoindexx{debugging information entry!ownership relation}
-debugging information entries (need explained
+debugging information entries (the need for which is explained
 below) within a \addtoindex{section group}
 can be given names of the form
 
@@ -300,7 +299,7 @@ symbol table, whether the current compilation references all
 those points or not.
 
 \textit{The completeness of the set of names generated is a
-quality\dash of\dash implementation issue.}
+quality-of-implementation issue.}
 
 It is up to the producer to ensure that if 
 \textless die\dash numbers\textgreater\ 
@@ -355,7 +354,7 @@ not a good candidate because the entities included are not
 necessarily file level entities.
 
 This also applies to \addtoindex{Fortran} INCLUDE lines when declarations
-are included into a procedure or module context.
+are included into a subprogram or module context.
 
 Consequently a compiler must use \DWTAGpartialunit{} (instead
 of \DWTAGcompileunit) 
@@ -451,7 +450,7 @@ the underlying object language is not (and varies from system to system).
 \subsubsection{C++ Example}
 
 The \addtoindex{C++} source 
-\addtoindexx{DWARF duplicate elimination!C++ example}
+\addtoindexx{DWARF duplicate elimination!examples}
 in 
 Figure \refersec{fig:duplicateeliminationexample1csource}
 is used to illustrate the DWARF
@@ -459,20 +458,20 @@ representation intended to allow duplicate elimination.
 
 \begin{figure}[ht]
 \textit{File wa.h}
-\begin{lstlisting}[numbers=none]
+\begin{nlnlisting}
 struct A {
    int i;
 };
-\end{lstlisting}
+\end{nlnlisting}
 \textit{File wa.c}
-\begin{lstlisting}[numbers=none]
+\begin{nlnlisting}
 #include "wa.h";
 int
 f(A &a)
 {
     return a.i + 2;
 }
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Duplicate elimination example \#1: C++ Source}
 \label{fig:duplicateeliminationexample1csource}
 \end{figure}
@@ -550,31 +549,52 @@ globally visible (in accordance with
 \DWTAGpartialunit{} 
 is not needed for the same reason.
 
+\needlines{6}
+\subsubsection{C Example}
+
+The \addtoindex{C++} example 
+\addtoindexx{DWARF duplicate elimination!examples}
+in this Section might appear to be equally
+valid as a \addtoindex{C} example. However, for \addtoindex{C} 
+it is prudent to include a \DWTAGimportedunit{}
+in the primary unit 
+(see Figure \refersec{fig:duplicateeliminationexample1primarycompilationunit})
+as well as an \DWATimport{} attribute that refers to the proper unit
+in the \addtoindex{section group}.
+
+\needlines{4}
+\textit{The \addtoindex{C} rules for consistency of global (file scope) symbols
+across compilations are less strict than for \addtoindex{C++}; inclusion
+of the import unit attribute assures that the declarations of
+the proper \addtoindex{section group} are considered before declarations
+from other compilations.}
+
+
 \subsubsection{Fortran Example}
 
 
 For a \addtoindex{Fortran}
-\addtoindexx{DWARF duplicate elimination!Fortran example}
+\addtoindexx{DWARF duplicate elimination!examples}
 example, consider 
 Figure \refersec{fig:duplicateeliminationexample2fortransource}.
 
-\begin{figure}
+\begin{figure}[ht]
 \textit{File CommonStuff.f\hspace{1pt}h}
 \addtoindexx{Fortran}
-\begin{lstlisting}[numbers=none]
+\begin{nlnlisting}
 IMPLICIT INTEGER(A-Z)
 COMMON /Common1/ C(100)
 PARAMETER(SEVEN = 7)
-\end{lstlisting}
+\end{nlnlisting}
 
 \textit{File Func.f}
-\begin{lstlisting}[numbers=none]
+\begin{nlnlisting}
 FUNCTION FOO (N)
 INCLUDE 'CommonStuff.fh'
 FOO = C(N + SEVEN)
 RETURN
 END
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Duplicate elimination example \#2: Fortran source} 
 \label{fig:duplicateeliminationexample2fortransource}
 \end{figure}
@@ -669,12 +689,12 @@ Figure \refersec{fig:duplicateeliminationexample2companionsource}
 
 \begin{figure}
 \textit{File Main.f} 
-\begin{lstlisting}[numbers=none]
+\begin{nlnlisting}
 INCLUDE 'CommonStuff.fh'
 C(50) = 8
 PRINT *, 'Result = ', FOO(50 - SEVEN)
 END
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Duplicate elimination example \#2: companion source }
 \label{fig:duplicateeliminationexample2companionsource}
 \end{figure}
@@ -722,26 +742,6 @@ because the included declarations are not independently
 visible as global entities.
 
 
-\needlines{6}
-\subsubsection{C++ Example}
-
-The \addtoindex{C++} example 
-\addtoindexx{DWARF duplicate elimination!C++ example}
-in this Section might appear to be equally
-valid as a \addtoindex{C} example. However, it is prudent to include
-a \DWTAGimportedunit{}
-in the primary unit 
-(see Figure \refersec{fig:duplicateeliminationexample1primarycompilationunit})
-with an \DWATimport{} attribute that refers to the proper unit
-in the \addtoindex{section group}.
-
-\textit{The \addtoindex{C} rules for consistency of global (file scope) symbols
-across compilations are less strict than for \addtoindexx{C++}; inclusion
-of the import unit attribute assures that the declarations of
-the proper \addtoindex{section group} are considered before declarations
-from other compilations.}
-
-
 \section{Using Type Units}
 \label{app:usingtypeunits}
 
@@ -793,8 +793,8 @@ consider a \addtoindex{C++} header file
 containing the type definitions shown
 in Figure \refersec{fig:typesignatureexamplescsource}.
 
-\begin{figure}[h]
-\begin{lstlisting}
+\begin{figure}[ht]
+\begin{nlnlisting}
 namespace N {
 
     struct B;
@@ -815,7 +815,7 @@ namespace N {
         struct C c;
     };
 }
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Type signature examples: C++ source}
 \label{fig:typesignatureexamplescsource}
 \end{figure}
@@ -908,7 +908,7 @@ Figure \refersec{fig:typesignaturecomputation1flattenedbytestream}.
     // Step 3: 'D' \DWTAGmember
     0x44 0x0d
     // Step 4: 'A' \DWATname \DWFORMstring "y"
-    0x41 0x03 0x08 0x78 0x00
+    0x41 0x03 0x08 0x79 0x00
     // Step 4: 'A' \DWATdatamemberlocation \DWFORMsdata 4
     0x41 0x38 0x0d 0x04
     // Step 6: 'R' \DWATtype (type \#2)
@@ -1025,7 +1025,7 @@ L5:
 \end{alltt}
 \end{dwflisting}
 \begin{center}
-\vspace{2mm}
+\vspace{3mm}
 Figure~\ref{fig:typesignaturecomputation2dwarfrepresentation}: Type signature computation \#2: DWARF representation \textit{(concluded)}
 \end{center}
 \end{figure}
@@ -1046,10 +1046,8 @@ to an incomplete type \texttt{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 \texttt{N::C}, using 
-\DWFORMrefsigeight{} to 
-refer to the type signature
-\addtoindexx{type signature}
-for that type.
+\DWFORMrefsigeight{} to refer to the type signature
+\addtoindexx{type signature} for that type.
 
 \begin{figure}
 \figurepart{1}{3}
@@ -1133,7 +1131,7 @@ for that type.
     // Step 6: 'T' \DWATtype (type \#4)
     0x54 0x49
         // Step 3: 'D' \DWTAGpointertype
-0x44 0x0f
+        0x44 0x0f
         // Step 5: 'N' \DWATtype
         0x4e 0x49
         // Step 5: 'C' \DWTAGnamespace "N" 'E'
@@ -1154,7 +1152,7 @@ for that type.
 \end{alltt}
 \end{dwflisting}
 \begin{center}
-\vspace{2mm}
+\vspace{3mm}
 Figure~\ref{fig:typesignatureexample2flattenedbytestream}: Type signature example \#2: flattened byte stream \textit{(continued)}
 \end{center}
 \end{figure}
@@ -1212,7 +1210,7 @@ Figure~\ref{fig:typesignatureexample2flattenedbytestream}: Type signature exampl
 \end{alltt}
 \end{dwflisting}
 \begin{center}
-\vspace{2mm}
+\vspace{3mm}
 Figure~\ref{fig:typesignatureexample2flattenedbytestream}: Type signature example \#2: flattened byte stream \textit{(concluded)}
 \end{center}
 \end{figure}
@@ -1233,7 +1231,7 @@ variable of type \texttt{N::A}, and its DWARF information may look
 like that shown in 
 Figure \refersec{fig:typesignatureexampleusage}.
 
-\begin{figure}[h]
+\begin{figure}[ht]
 \begin{dwflisting}
 \begin{alltt}
   \DWTAGcompileunit
@@ -1261,7 +1259,7 @@ how the bytes of the flattened type description are formed
 during the type signature computation algorithm of
 Section \refersec{datarep:typesignaturecomputation}. 
 
-\begin{figure}[h]
+\begin{figure}[ht]
 \begin{dwflisting}
 %FIXME: The index entries here with \addtoindexx are ineffective.
 \begin{alltt}
@@ -1282,7 +1280,7 @@ attribute
     : 'T' at-code signature              // Recursive type
 children                 //  Step 7
     : child children
-    : '0'
+    : '\textbackslash{}0'
 child
     : 'S' tag-code string
     : signature
@@ -1296,13 +1294,13 @@ form-encoded-value
     : \DWFORMstring string \addtoindexx{string class}
     : \DWFORMblock \nolink{block} \addtoindexx{block class}
 \DWFORMstring \addtoindexx{string class}
-    : 'x08'
+    : '\textbackslash{}x08'
 \DWFORMblock  \addtoindexx{block class}
-    : 'x09'
+    : '\textbackslash{}x09'
 \DWFORMflag \addtoindexx{flag class}
-    : 'x0c'
+    : '\textbackslash{}x0c'
 \DWFORMsdata \addtoindexx{constant class}
-    : 'x0d'
+    : '\textbackslash{}x0d'
 value
     : <SLEB128>
 \nolink{block}
@@ -1329,7 +1327,7 @@ A possible representation of the
 debug information for this function in the compilation unit is shown
 in Figure \refersec{fig:completingedeclarationofamemberfunctiondwarf}.
 
-\begin{figure}[h]
+\begin{figure}[ht]
 \begin{dwflisting}
 \begin{alltt}
   \DWTAGnamespace
@@ -1408,7 +1406,7 @@ sections such as the base object file
 
 Function templates (C++) result in code for the same template
 instantiation being compiled into multiple archives or
-relocatable objects. The linker wants to keep only one of a
+relocatable object files. The linker wants to keep only one of a
 given entity. The DWARF description, and everything else for
 this function, should be reduced to just a single copy.