compression.tex
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
index da4d351..d6e7c33 100644 (file)
@@ -5,7 +5,11 @@
 % captioning as DWARF4 here with figures as they moved (floated)
 % making it hard to follow.  Hence this uses fewer figures.
 
-DWARF can use a lot of disk space.
+DWARF 
+\addtoindexx{DWARF compression}
+can 
+\addtoindexx{DWARF duplicate elimination}
+use a lot of disk space.
 
 This is especially true for C++, where the depth and complexity
 of headers can mean that many, many (possibly thousands of)
@@ -156,7 +160,9 @@ widely known as ``COMDATs'' or ``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
-of the DWARF duplicate elimination techniques described here.}
+of the 
+\addtoindexx{duplication elimination|see{DWARF duplicate elimination}}
+DWARF duplicate elimination techniques described here.}
 
 \subsection{Naming and Usage Considerations}
 \label{app:namingandusageconsiderations}
@@ -179,7 +185,8 @@ Section \refersec{app:examples}.
 
 \textbf{Section Group Names}
 
-Section groups must have a section group name. For the subsequent C++ example, a name like
+Section groups must have a section group name. For the subsequent 
+\addtoindex{C++} example, a name like
 
 <producer-prefix>.<file-designator>.<gid-number>
 
@@ -231,7 +238,9 @@ above is given the name \textit{my.compiler.company.cpp.wa.h.123456}.
 
 \textbf{Debugging Information Entry Names}
 
-Global labels for debugging information entries (need explained
+Global labels for 
+\addtoindexx{debugging information entry!ownership relation}
+debugging information entries (need explained
 below) within a section group can be given names of the form
 
 \begin{alltt}
@@ -317,7 +326,7 @@ An \#include directive appearing outside any other
 declarations is a good candidate to be represented using
 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}. 
 However, an \#include appearing inside
-a C++ namespace declaration or a function, for example, is
+a \addtoindex{C++} namespace declaration or a function, for example, is
 not a good candidate because the entities included are not
 necessarily file level entities.
 
@@ -384,7 +393,9 @@ same object file.
 \subsection{Examples}
 \label{app:examples}
 
-This section provides several examples in order to have a
+This section provides several 
+\addtoindexx{DWARF duplicate elimination!examples}
+examples in order to have a
 concrete basis for discussion.
 
 In these examples, the focus is on the arrangement of DWARF
@@ -405,7 +416,9 @@ the underlying object language is not (and varies from system to system).
 
 \subsubsection{C++ Example}
 
-The C++ source in 
+The addtoindex{C++} source 
+\addtoindexx{DWARF duplicate elimination!C++ example}
+in 
 Section \refersec{app:duplicateeliminationexample1csource}
 is used to illustrate the DWARF
 representation intended to allow duplicate elimination.
@@ -492,13 +505,16 @@ in the section group shown above.
 
 This example uses \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} for the section group,
 implying that the contents of the compilation unit are
-globally visible (in accordance with C++ language rules).
+globally visible (in accordance with 
+\addtoindex{C++} language rules).
 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} is not needed for the same reason.
 
 \subsubsection{Fortran Example}
 
 
-For a Fortran example, consider 
+For a Fortran 
+\addtoindexx{DWARF duplicate elimination!Fortran example}
+example, consider 
 Figure \refersec{app:duplicateeliminationexample2fortransource}.
 
 
@@ -658,13 +674,17 @@ visible as global entities.
 
 \subsubsection{C Example}
 
-The C++ example in this Section might appear to be equally
-valid as a C example. However, it is prudent to include
-a \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit} in the primary unit (see Figure 84)
+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}
+in the primary unit 
+(see Figure \refersec{app:duplicateeliminationexample1primarycompilationunit})
 with an \livelink{chap:DWATimport}{DW\-\_AT\-\_import} attribute that refers to the proper unit
 in the section group.
 
-\textit{The C rules for consistency of global (file scope) symbols
+\textit{The \addtoindex{C} rules for consistency of global (file scope) symbols
 across compilations are less strict than for C++; inclusion
 of the import unit attribute assures that the declarations of
 the proper section group are considered before declarations
@@ -717,7 +737,7 @@ Section \refersec{datarep:typesignaturecomputation}.
 \subsection{Signature Computation Example}
 \label{app:signaturecomputationexample}
 
-As an example, consider a C++ header file 
+As an example, consider a \addtoindex{C++} header file 
 containing the type definitions shown
 in Section \refersec{app:typesignatureexamplescsource}.
 
@@ -1192,9 +1212,12 @@ empty
 \subsection{\#include compression}
 \label{app:includecompression}
 
-C++ has a much greater problem than C with the number and
+\addtoindex{C++} has a much greater 
+problem than 
+\addtoindex{C} with the number and
 size of the headers included and the amount of data in each,
-but even with C there is substantial header file information
+but even with \addtoindex{C} 
+there is substantial header file information
 duplication.
 
 A reasonable approach is to put each header file in its own