This completes (many!) changes resulting from reviews over the
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
index eb9c847..229399d 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).
 
@@ -250,7 +250,7 @@ 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
@@ -399,8 +399,8 @@ unit's debugging information entries to those of another
 compilation unit.
 
 When referencing into a removable \addtoindex{section group}
-\addtoindex{.debug\_info}
-from another \addtoindex{.debug\_info} (from anywhere), the
+\dotdebuginfo{}
+from another \dotdebuginfo{} (from anywhere), the
 \texttt{<prefix>.<file-designator>.<gid-number>.<die-number>}
 name should be used for an external symbol and a relocation
 generated based on that name.
@@ -408,8 +408,8 @@ generated based on that name.
 \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
@@ -426,17 +426,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 +482,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})
@@ -516,9 +516,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}
@@ -585,7 +585,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 +631,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 +674,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 +683,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}
@@ -741,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
+\dotdebugtypes{} section
 and arranging for the linker to recognize and eliminate
 duplicates at the individual type level.
 
@@ -754,15 +754,15 @@ 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}
 
 As discussed in the previous section 
@@ -774,7 +774,7 @@ 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}.
@@ -859,7 +859,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 
@@ -1024,10 +1024,10 @@ Figure~\ref{fig:typesignaturecomputation2dwarfrepresentation} Type signature com
 \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
 types. The information for each of these referenced types is
@@ -1036,16 +1036,16 @@ 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}.
@@ -1222,7 +1222,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 +1334,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}
@@ -1358,7 +1358,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 +1382,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