A few miscelleaneous corrections including especially fixing the spacing
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
index eb9c847..dd81740 100644 (file)
@@ -55,24 +55,24 @@ A traditional relocatable object output
 from a single compilation might contain sections 
 named:
 \begin{alltt}
-    \addtoindex{.data}
-    \addtoindex{.text}
-    \addtoindex{.debug\_info}
-    \addtoindex{.debug\_abbrev}
-    \addtoindex{.debug\_line}
-    \addtoindex{.debug\_aranges}
+    \dotdata{}
+    \dottext{}
+    \dotdebuginfo{}
+    \dotdebugabbrev{}
+    \dotdebugline{}
+    \dotdebugaranges{}
 \end{alltt}
 A relocatable object from a compilation system 
 attempting duplicate DWARF elimination might
 contain sections as in:
 
 \begin{alltt}
-    \addtoindex{.data}
-    \addtoindex{.text}
-    \addtoindex{.debug\_info}
-    \addtoindex{.debug\_abbrev}
-    \addtoindex{.debug\_line}
-    \addtoindex{.debug\_aranges}
+    \dotdata{}
+    \dottext{}
+    \dotdebuginfo{}
+    \dotdebugabbrev{}
+    \dotdebugline{}
+    \dotdebugaranges{}
 \end{alltt}
 
 followed (or preceded, the order is not significant) 
@@ -81,18 +81,18 @@ by a series of
 section groups:
 \begin{alltt}
 ==== Section group 1
-    \addtoindex{.debug\_info}
-    \addtoindex{.debug\_abbrev}
-    \addtoindex{.debug\_line}
+    \dotdebuginfo{}
+    \dotdebugabbrev{}
+    \dotdebugline{}
 ==== ...
 ==== Section group N
-    \addtoindex{.debug\_info}
-    \addtoindex{.debug\_abbrev}
-    \addtoindex{.debug\_line}
+    \dotdebuginfo{}
+    \dotdebugabbrev{}
+    \dotdebugline{}
 \end{alltt}
 
 where each \addtoindex{section group} might or might not contain executable
-code (\textit{.text} sections) or data (\textit{.data} sections).
+code (\dottext{} sections) or data (\dotdata{} sections).
 
 \needlines{6}
 A \textit{\addtoindex{section group}} is a named set 
@@ -144,13 +144,13 @@ 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 \addtoindex{.debug\_info}
+\item A means of referencing from inside one \dotdebuginfo{}
 compilation unit to another 
-\addtoindex{.debug\_info} compilation unit
+\dotdebuginfo{} compilation unit
 (\livelink{chap:DWFORMrefaddr}{DW\_FORM\_ref\_addr} provides this).
 
 \item A means of having multiple contributions to specific sections
-(for example, \addtoindex{.debug\_info}, and so on) in a single object file.
+(for example, \dotdebuginfo{}, and so on) in a single object file.
 
 \item  A means of identifying a \addtoindex{section group} (giving it a name).
 
@@ -169,7 +169,7 @@ corresponds closely to the similarly named concepts in the
 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
+widely known as \doublequote{COMDATs} or \doublequote{COMDAT sections.} (Other
 object file representations provide COMDAT\dash style mechanisms as
 well.) There are several variations in the COMDAT schemes in
 common use, any of which should be sufficient for the purposes
@@ -233,7 +233,7 @@ the same
 \textless gid\dash number\textgreater,
 and
 
-\item  a non\dash matching output (say because of \#defines)
+\item  a non\dash matching output (say because of \texttt{\#defines})
 generates a different 
 \textless gid\dash number\textgreater.
 \end{itemize}
@@ -243,14 +243,14 @@ generates a different
 \textit{It may be useful to think of a 
 \textless gid\dash number\textgreater
 as a kind
-of ``digital signature'' that allows a fast test for the
+of \doublequote{digital signature} that allows a fast test for the
 equality of two 
 \addtoindexx{section group}
 section groups.}
 
 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}.
+above is given the name \texttt{my.compiler.company.cpp.wa.h.123456}.
 
 
 
@@ -292,7 +292,7 @@ during compilation.
 In general, every point in the 
 \addtoindexx{section group}
 section group 
-\addtoindex{.debug\_info} that
+\dotdebuginfo{} that
 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
@@ -398,22 +398,26 @@ Use
 unit's debugging information entries to those of another
 compilation unit.
 
+\needlines{4}
 When referencing into a removable \addtoindex{section group}
-\addtoindex{.debug\_info}
-from another \addtoindex{.debug\_info} (from anywhere), the
-\texttt{<prefix>.<file-designator>.<gid-number>.<die-number>}
+\dotdebuginfo{}
+from another \dotdebuginfo{} (from anywhere), the
+\begin{alltt}
+    <prefix>.<file-designator>.<gid-number>.<die-number>
+\end{alltt}
 name should be used for an external symbol and a relocation
 generated based on that name.
 
+\needlines{4}
 \textit{When referencing into a 
 \addtoindexx{section group}
 non-section group 
-\addtoindex{.debug\_info},
-from another \addtoindex{.debug\_info} (from anywhere) 
+\dotdebuginfo{},
+from another \dotdebuginfo{} (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
+\doublequote{internal name}) may be used for references within the
 same object file.}
 
 \subsection{Examples}
@@ -426,17 +430,17 @@ concrete basis for discussion.
 
 In these examples, the focus is on the arrangement of DWARF
 information into sections (specifically the 
-\addtoindex{.debug\_info}
+\dotdebuginfo{}
 section) and the naming conventions used to achieve references
 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}, 
-\addtoindex{.debug\_aranges}, or others);
-however, only the \addtoindex{.debug\_info}
+\dotdebuginfo{}
+(for example, \dotdebugline{}, 
+\dotdebugaranges{}, or others);
+however, only the \dotdebuginfo{}
 section is shown to keep the
 examples compact and easier to read.
 
@@ -482,7 +486,7 @@ wa.h.
 \begin{alltt}
 ==== Section group name:
     my.compiler.company.cpp.wa.h.123456
-== section \addtoindex{.debug\_info}
+== section \dotdebuginfo{}
 DW.cpp.wa.h.123456.1:     ! linker global symbol
     \livelink{chap:DWTAGcompileunit}{DW\_TAG\_compile\_unit}
         \livelink{chap:DWATlanguage}{DW\_AT\_language}(\livelink{chap:DWLANGCplusplus}{DW\_LANG\_C\_plus\_plus})
@@ -508,7 +512,7 @@ DW.cpp.wa.h.123456.4:     ! linker global symbol
 \end{figure}
 
 Figure \refersec{fig:duplicateeliminationexample1primarycompilationunit}
-shows the ``normal'' DWARF sections, which are not part of
+shows the \doublequote{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.
@@ -516,9 +520,9 @@ in the \addtoindex{section group} shown above.
 \begin{figure}
 \begin{dwflisting}
 \begin{alltt}
-== section .text
+== section \dottext{}
     [generated code for function f]
-== section \addtoindex{.debug\_info}
+== section \dotdebuginfo{}
     \livelink{chap:DWTAGcompileunit}{DW\_TAG\_compile\_unit}
 .L1:                           ! local (non-linker) symbol
         \livelink{chap:DWTAGreferencetype}{DW\_TAG\_reference\_type}
@@ -536,11 +540,14 @@ in the \addtoindex{section group} shown above.
 \label{fig:duplicateeliminationexample1primarycompilationunit}
 \end{figure}
 
-This example uses \livelink{chap:DWTAGcompileunit}{DW\_TAG\_compile\_unit} for the \addtoindex{section group},
+\needlines{4}
+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).
-\livelink{chap:DWTAGpartialunit}{DW\_TAG\_partial\_unit} is not needed for the same reason.
+\livelink{chap:DWTAGpartialunit}{DW\_TAG\_partial\_unit} 
+is not needed for the same reason.
 
 \subsubsection{Fortran Example}
 
@@ -551,7 +558,7 @@ example, consider
 Figure \refersec{fig:duplicateeliminationexample2fortransource}.
 
 \begin{figure}
-\textit{File CommonStuff.fh}
+\textit{File CommonStuff.f\hspace{1pt}h}
 \addtoindexx{Fortran}
 \begin{lstlisting}[numbers=none]
 IMPLICIT INTEGER(A-Z)
@@ -585,7 +592,7 @@ CommonStuff.fh.
 
     my.f90.company.f90.CommonStuff.fh.654321
 
-== section \addtoindex{.debug\_info}
+== section \dotdebuginfo{}
 
 DW.myf90.CommonStuff.fh.654321.1:    ! linker global symbol
     \livelink{chap:DWTAGpartialunit}{DW\_TAG\_partial\_unit}
@@ -631,10 +638,10 @@ shows the sections for the primary compilation unit.
 \begin{figure}
 \begin{dwflisting}
 \begin{alltt}
-== section .text
+== section \dottext{}
     [code for function Foo]
 
-== section \addtoindex{.debug\_info}
+== section \dotdebuginfo{}
     \livelink{chap:DWTAGcompileunit}{DW\_TAG\_compile\_unit}
         \livelink{chap:DWTAGsubprogram}{DW\_TAG\_subprogram}
             \livelink{chap:DWATname}{DW\_AT\_name}("Foo")
@@ -674,7 +681,7 @@ END
 \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 
+\texttt{my.f90.company.f90.CommonStuff.fh.654321} 
 corresponding to the
 included file as well as the remainder of the main subprogram
 as shown in 
@@ -683,7 +690,7 @@ Figure \refersec{fig:duplicateeliminationexample2companiondwarf}.
 \begin{figure}
 \begin{dwflisting}
 \begin{alltt}
-== section \addtoindex{.debug\_info}
+== section \dotdebuginfo{}
     \livelink{chap:DWTAGcompileunit}{DW\_TAG\_compile\_unit}
         \livelink{chap:DWATname}{DW\_AT\_name}(F90\$main)
         \livelink{chap:DWTAGbasetype}{DW\_TAG\_base\_type}
@@ -715,10 +722,10 @@ visible as global entities.
 
 
 \needlines{6}
-\subsubsection{C Example}
+\subsubsection{C++ Example}
 
-The \addtoindex{C} example 
-\addtoindexx{DWARF duplicate elimination!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 \livelink{chap:DWTAGimportedunit}{DW\_TAG\_imported\_unit}
@@ -741,7 +748,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
+\dotdebugtypes{} section
 and arranging for the linker to recognize and eliminate
 duplicates at the individual type level.
 
@@ -754,27 +761,28 @@ implementation, the relocatable object file may contain one
 of each of these debug sections:
 
 \begin{alltt}
-\addtoindex{.debug\_abbrev}
-\addtoindex{.debug\_info}
-\addtoindex{.debug\_line}
+\dotdebugabbrev{}
+\dotdebuginfo{}
+\dotdebugline{}
 \end{alltt}
 
 and any number of these additional sections:
 
 \begin{alltt}
-\addtoindex{.debug\_types}
+\dotdebugtypes{}
 \end{alltt}
 
+\needlines{5}
 As discussed in the previous section 
 (Section \refersec{app:usingcompilationunits}), 
 many
 linkers today support the concept of a COMDAT group or
-linkonce section. The general idea is that a ``key'' can be
+linkonce section. The general idea is that a \doublequote{key} can be
 attached to a section or a group of sections, and the linker
 will include only one copy of a \addtoindex{section group}
 (or individual section) for any given key. 
 For 
-\addtoindex{.debug\_types} sections, the
+\dotdebugtypes{} sections, the
 key is the \addtoindex{type signature}
 formed from the algorithm given in
 Section \refersec{datarep:typesignaturecomputation}.
@@ -818,7 +826,7 @@ namespace N {
 Next, consider one possible representation of the DWARF
 information that describes the type \doublequote{struct C} as shown
 in 
-\refersec{fig:typesignaturecomputation1dwarfrepresentation}:
+\refersec{fig:typesignaturecomputation1dwarfrepresentation}.
 
 \begin{figure}
 \begin{dwflisting}
@@ -859,7 +867,7 @@ L2:
 \end{figure}
 
 \needlines{3}
-In computing a signature for the type N::C, flatten the type
+In computing a signature for the type \texttt{N::C}, flatten the type
 \addtoindexx{type signature}
 description into a byte stream according to the procedure
 outlined in 
@@ -924,7 +932,7 @@ 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 
+describes the type \doublequote{class A} as shown in 
 Figure \refersec{fig:typesignaturecomputation2dwarfrepresentation}.
 
 \begin{figure}
@@ -1020,32 +1028,33 @@ L5:
 \end{alltt}
 \end{dwflisting}
 \begin{center}
-Figure~\ref{fig:typesignaturecomputation2dwarfrepresentation} Type signature computation \#2: DWARF representation \textit{(concluded)}
+\vspace{2mm}
+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
+In this example, the structure types \texttt{N::A} and \texttt{N::C} have each
 been placed in separate 
 \addtoindexx{type unit}
-type units.  For N::A, the actual
+type units.  For \texttt{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
+involves references to the \texttt{int} base type and to two pointer
 types. The information for each of these referenced types is
 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 \addtoindex{type unit}. 
 The last pointer type contains a reference
-to an incomplete type N::B, which is also included here as
+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 N::C, using 
+to \texttt{N::C}, using 
 \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
+In computing a signature for the type \texttt{N::A}, flatten the type
 description into a byte stream according to the procedure
 outlined in 
 Section \refersec{datarep:typesignaturecomputation}.
@@ -1155,7 +1164,8 @@ Figure \refersec{fig:typesignatureexample2flattenedbytestream}.
 \end{alltt}
 \end{dwflisting}
 \begin{center}
-Figure~\ref{fig:typesignatureexample2flattenedbytestream} Type signature example \#2: flattened byte stream \textit{(continued)}
+\vspace{2mm}
+Figure~\ref{fig:typesignatureexample2flattenedbytestream}: Type signature example \#2: flattened byte stream \textit{(continued)}
 \end{center}
 \end{figure}
     
@@ -1212,7 +1222,8 @@ Figure~\ref{fig:typesignatureexample2flattenedbytestream} Type signature example
 \end{alltt}
 \end{dwflisting}
 \begin{center}
-Figure~\ref{fig:typesignatureexample2flattenedbytestream} Type signature example \#2: flattened byte stream \textit{(concluded)}
+\vspace{2mm}
+Figure~\ref{fig:typesignatureexample2flattenedbytestream}: Type signature example \#2: flattened byte stream \textit{(concluded)}
 \end{center}
 \end{figure}
 
@@ -1222,7 +1233,7 @@ 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
+variable of type \texttt{N::A}, and its DWARF information may look
 like that shown in 
 Figure \refersec{fig:typesignatureexampleusage}.
 
@@ -1334,7 +1345,7 @@ 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.
+\dotdebuginfo{} section.
 
 \subsection{Eliminating function duplication}
 \label{app:eliminatingfunctionduplication}
@@ -1346,6 +1357,7 @@ relocatable objects. 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.
 
+\needlines{5}
 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
@@ -1358,7 +1370,7 @@ by the static linker are simply discarded.
 
 
 References to other 
-\addtoindex{.debug\_info} sections follow the approach
+\dotdebuginfo{} sections follow the approach
 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}.
@@ -1382,9 +1394,9 @@ text, data, and DWARF sections.
 
 There will also be a compilation unit that has the file\dash level
 declarations and definitions. Other per\dash function compilation
-unit DWARF information (
-\addtoindex{.debug\_info}) points to this common
-file\dash level compilation unit using \livelink{chap:DWTAGimportedunit}{DW\_TAG\_imported\_unit}.
+unit DWARF information (\dotdebuginfo{}) points to this common
+file\dash level compilation unit using 
+\livelink{chap:DWTAGimportedunit}{DW\_TAG\_imported\_unit}.
 
 Section groups can use \livelink{chap:DWFORMrefaddr}{DW\_FORM\_ref\_addr} and internal labels
 (section\dash relative relocations) to refer to the main object