Corrects verbatim to be alltt in one crucial spot
[dwarf-doc.git] / dwarf5 / latexdoc / typeentries.tex
index ddeaad3..d61a378 100644 (file)
@@ -71,7 +71,9 @@ the base type entry may also have
 a 
 \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} and a
 \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} attribute, 
-both of whose values are
+both 
+\addtoindexx{data bit offset attribute}
+of whose values are
 integer constant values (
 see Section \refersec{chap:staticanddynamicvaluesofattributes}). 
 The bit size
@@ -90,7 +92,10 @@ of zero is assumed.
 \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} 
 is 
 \addtoindexx{bit offset attribute}
-new in DWARF Version 4 and
+new 
+\addtoindexx{data bit offset attribute}
+in 
+\addtoindex{DWARF Version 4} and
 is also used for bit field members 
 (see Section \refersec{chap:datamemberentries}). 
 It
@@ -105,11 +110,14 @@ big\dash endian architectures but which is wasteful for use on
 little\dash endian architectures.}
 
 \textit{The attribute \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} is 
-deprecated in DWARF Version
-4 for use in base types, but implementations may continue to
+deprecated in 
+\addtoindex{DWARF Version 4}
+for use in base types, but implementations may continue to
 support its use for compatibility.}
 
-\textit{The DWARF Version 3 definition of these attributes is as follows.}
+\textit{The 
+\addtoindex{DWARF Version 3}
+definition of these attributes is as follows.}
 
 \begin{myindentpara}{1cm}
 \textit{A base type entry has a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}
@@ -133,7 +141,12 @@ high order bit of a value of the given type from the high
 order bit of the storage unit used to contain that value.}
 \end{myindentpara}
 
-\textit{In comparing DWARF Versions 3 and 4, note that DWARF V4
+\textit{In comparing 
+DWARF Versions 3 
+\addtoindexx{DWARF Version 3}
+and 
+\addtoindexx{DWARF Version 4} and 
+4, note that DWARF V4
 defines the following combinations of attributes:}
 
 \begin{itemize}
@@ -143,7 +156,9 @@ defines the following combinations of attributes:}
 \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} 
 and optionally \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}}
 \end{itemize}
-DWARF V3 defines the following combinations:
+DWARF V3 
+\addtoindexx{DWARF Version 3}
+defines the following combinations:
 % FIXME: the figure below interferes with the following
 % bullet list, which looks horrible as a result.
 \begin{itemize}
@@ -201,8 +216,14 @@ and
 \livelink{chap:DWATEnumericstring}{DW\-\_ATE\-\_numeric\-\_string} 
 base types
 represent packed and unpacked decimal string numeric data
-types, respectively, either of which may be either signed
-or unsigned. 
+types, respectively, either of which may be 
+either 
+\addtoindexx{decimal scale attribute}
+signed
+\addtoindexx{decimal sign attribute}
+or 
+\addtoindexx{digit count attribute}
+unsigned. 
 \hypertarget{chap:DWATdecimalsigndecimalsignrepresentation}
 These 
 \hypertarget{chap:DWATdigitcountdigitcountforpackeddecimalornumericstringtype}
@@ -212,7 +233,9 @@ base types are used in combination with
 \livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale}
 attributes.
 
-A \livelink{chap:DWATdecimalsign}{DW\-\_AT\-\_decimal\-\_sign} attribute is an integer constant that
+A \livelink{chap:DWATdecimalsign}{DW\-\_AT\-\_decimal\-\_sign} attribute 
+\addtoindexx{decimal sign attribute}
+is an integer constant that
 conveys the representation of the sign of the decimal type
 (see Figure \refersec{fig:decimalsignattributevalues}). 
 Its integer constant value is interpreted to
@@ -222,13 +245,17 @@ alternatively, no sign at all.
 
 The 
 \livelink{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count}
-attribute is an integer constant
+attribute 
+\addtoindexx{digit count attribute}
+is an integer constant
 value that represents the number of digits in an instance of
 the type.
 
 \hypertarget{chap:DWATdecimalscaledecimalscalefactor}
 The \livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale}
-attribute is an integer constant value
+attribute 
+\addtoindexx{decimal scale attribute}
+is an integer constant value
 that represents the exponent of the base ten scale factor to
 be applied to an instance of the type. A scale of zero puts the
 decimal point immediately to the right of the least significant
@@ -250,15 +277,21 @@ string associated with the type.
 
 If the edited base type entry describes an edited numeric
 data type, the edited type entry has a \livelink{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count} and a
-\livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale} attribute. These attributes have the same
-interpretation as described for the \livelink{chap:DWATEpackeddecimal}{DW\-\_ATE\-\_packed\-\_decimal} and
-\livelink{chap:DWATEnumericstring}{DW\-\_ATE\-\_numeric\-\_string} base types. If the edited type entry
+\livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale} attribute. 
+\addtoindexx{decimal scale attribute}
+These attributes have the same
+interpretation as described for the 
+\livelink{chap:DWATEpackeddecimal}{DW\-\_ATE\-\_packed\-\_decimal} and
+\livelink{chap:DWATEnumericstring}{DW\-\_ATE\-\_numeric\-\_string} base 
+types. If the edited type entry
 describes an edited alphanumeric data type, the edited type
 entry does not have these attributes.
 
 
 \textit{The presence or absence of the \livelink{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count} and
-\livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale} attributes allows a debugger to easily
+\livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale} attributes 
+\addtoindexx{decimal scale attribute}
+allows a debugger to easily
 distinguish edited numeric from edited alphanumeric, although
 in principle the digit count and scale are derivable by
 interpreting the picture string.}
@@ -267,20 +300,30 @@ The \livelink{chap:DWATEsignedfixed}{DW\-\_ATE\-\_signed\-\_fixed} and \livelink
 describe signed and unsigned fixed\dash point binary data types,
 respectively.
 
-The fixed binary type entries have a \livelink{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count}
+The fixed binary type entries have 
+\addtoindexx{digit count attribute}
+a 
+\livelink{chap:DWATdigitcount}{DW\-\_AT\-\_digit\-\_count}
 attribute with the same interpretation as described for the
 \livelink{chap:DWATEpackeddecimal}{DW\-\_ATE\-\_packed\-\_decimal} and \livelink{chap:DWATEnumericstring}{DW\-\_ATE\-\_numeric\-\_string} base types.
 
 For a data type with a decimal scale factor, the fixed binary
-type entry has a \livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale} attribute with the same
-interpretation as described for the \livelink{chap:DWATEpackeddecimal}{DW\-\_ATE\-\_packed\-\_decimal}
+type entry has a 
+\livelink{chap:DWATdecimalscale}{DW\-\_AT\-\_decimal\-\_scale} attribute 
+\addtoindexx{decimal scale attribute}
+with the same
+interpretation as described for the 
+\livelink{chap:DWATEpackeddecimal}{DW\-\_ATE\-\_packed\-\_decimal}
 and \livelink{chap:DWATEnumericstring}{DW\-\_ATE\-\_numeric\-\_string} base types.
 
 \hypertarget{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}
 For a data type with a binary scale factor, the fixed
 \addtoindexx{binary scale attribute}
-binary type entry has a \livelink{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} attribute. The
-\livelink{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} attribute is an integer constant value
+binary type entry has a 
+\livelink{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} attribute. 
+The
+\livelink{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} attribute 
+is an integer constant value
 that represents the exponent of the base two scale factor to
 be applied to an instance of the type.  Zero scale puts the
 binary point immediately to the right of the least significant
@@ -406,6 +449,7 @@ or reference type ought to be dereferenced.
 A modified type entry describing a shared qualified type
 (using \livelink{chap:DWTAGsharedtype}{DW\-\_TAG\-\_shared\-\_type}) may have a
 \livelink{chap:DWATcount}{DW\-\_AT\-\_count} attribute
+\addtoindexx{count attribute}
 whose value is a constant expressing the blocksize of the
 type. If no count attribute is present, then the “infinite”
 blocksize is assumed.
@@ -442,14 +486,12 @@ rvalue reference to an object of the type being modified
 \label{fig:typemodifiertags}
 \end{figure}
 
-% The following prevents splitting the examples up.
-% FIXME perhaps there is a better way. We could box the verbatim, 
-% see memman.pdf on verbatims.
+%The following clearpage prevents splitting the example across pages.
 \clearpage
-\textit{As examples of how tye modifiers are ordered, take the following C
+\textit{As examples of how type modifiers are ordered, take the following C
 declarations:}
 
-\begin{verbatim}
+\begin{alltt}
 const unsigned char * volatile p;
     which represents a volatile pointer to a constant
     character. This is encoded in DWARF as:
@@ -469,7 +511,7 @@ volatile unsigned char * const restrict p;
                         \livelink{chap:DWTAGvolatiletype}{DW\-\_TAG\-\_volatile\-\_type} -->
                             \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}(unsigned char)
 
-\end{verbatim}
+\end{alltt}
 
 \section{Typedef Entries}
 \label{chap:typedefentries}
@@ -667,6 +709,7 @@ to hold an instance of the structure, union or class type,
 including any padding.  An incomplete structure, union or
 class type is represented by a structure, union or class
 entry that does not have a byte size attribute and that has
+\addtoindexx{declaration attribute}
 a \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} attribute.
 
 If the complete declaration of a type has been placed in
@@ -694,7 +737,9 @@ class or union they represent if such information is already
 provided in the declaration.
 
 \textit{For \addtoindex{C} and \addtoindex{C++}, 
-data member declarations occurring within
+data 
+\addtoindexx{data member|see {member entry (data)}}
+member declarations occurring within
 the declaration of a structure, union or class type are
 considered to be “definitions” of those members, with
 the exception of “static” data members, whose definitions
@@ -756,7 +801,10 @@ declarations in the source program.
 \subsection{Derived or Extended Structs, Classes and Interfaces}
 \label{chap:derivedorextendedstructsclasesandinterfaces}
 
-\textit{In \addtoindex{C++}, a class (or struct) may be ``derived from'' or be a
+\textit{In \addtoindex{C++}, a class (or struct) 
+may 
+\addtoindexx{derived type (C++)|see{inheritance entry}}
+be ``derived from'' or be a
 ``subclass of'' another class. In Java, an interface may ``extend''
 one or more other interfaces, and a class may ``extend'' another
 class and/or ``implement'' one or more interfaces. All of these
@@ -779,7 +827,9 @@ of the inheritance entry is derived, extended or implementing.
 
 An inheritance entry for a class that derives from or extends
 \hypertarget{chap:DWATdatamemberlocationinheritedmemberlocation}
-another class or struct also has a 
+another class or struct also has 
+\addtoindexx{data member location attribute}
+a 
 \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location}
 attribute, whose value describes the location of the beginning
 of the inherited type relative to the beginning address of the
@@ -813,7 +863,8 @@ the class referenced by the inheritance entry serves
 as a \addtoindex{C++} virtual base class, the inheritance entry has a
 \livelink{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality} attribute.
 
-\textit{For a \addtoindex{C++} virtual base, the data member location attribute
+\textit{For a \addtoindex{C++} virtual base, the 
+\addtoindex{data member location attribute}
 will usually consist of a non-trivial location description.}
 
 \subsection{Access Declarations}
@@ -913,7 +964,9 @@ The member entry corresponding to a data member that is
 \hypertarget{chap:DWATdatabitoffsetdatamemberbitlocation}
 defined 
 \hypertarget{chap:DWATdatamemberlocationdatamemberlocation}
-in a structure, union or class may have either a
+in a structure, union or class may have either
+\addtoindexx{data member location attribute}
+a
 \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} attribute or a
 \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}
 attribute. If the beginning of the data member is the same as
@@ -921,6 +974,8 @@ the beginning of the containing entity then neither attribute
 is required.
 
 For a \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} attribute
+
+\addtoindexx{data member location attribute}
 there are two cases:
 
 \begin{enumerate}[1.]
@@ -948,7 +1003,9 @@ result of the evaluation is a location--either an address or
 the name of a register, not an offset to the member.}
 
 \textit{A \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} 
-attribute that has the form of a
+attribute 
+\addtoindexx{data member location attribute}
+that has the form of a
 location description is not valid for a data member contained
 in an entity that is not byte aligned because DWARF operations
 do not allow for manipulating or computing bit offsets.}
@@ -975,8 +1032,13 @@ is the amount
 of storage needed to hold the value of the data member.
 
 \textit{\addtoindex{C} and \addtoindex{C++} 
+typically 
 \addtoindex{bit fields} 
-typically require the use of the
+require the use 
+\addtoindexx{data bit offset}
+of 
+\addtoindexx{data bit size}
+the
 \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} and 
 \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attributes.}
 
@@ -1073,7 +1135,9 @@ and arrays, see
 Appendix \refersec{app:pascalexample}.}
 
 \textit{Attribute \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} 
-is new in DWARF Version 4 and is also used for base types 
+is new in 
+\addtoindex{DWARF Version 4}
+and is also used for base types 
 (see Section 
 \refersec{chap:basetypeentries}). 
 It replaces the
@@ -1095,7 +1159,9 @@ attribute combination is deprecated for data members in DWARF
 Version 4, but implementations may continue to support this
 use for compatibility.}
 
-\textit{The DWARF Version 3 definitions of these attributes are
+\textit{The 
+\addtoindex{DWARF Version 3} 
+definitions of these attributes are
 as follows.}
 
 \begin{myindentpara}{1cm}
@@ -1145,9 +1211,15 @@ the bit field is the value of the bit offset attribute.}
 \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}, 
 \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} and 
 \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} attribute
-combination may be found in the DWARF Version 3 Standard.}
+combination may be found in the 
+\addtoindex{DWARF Version 3} Standard.}
 
-\textit{In comparing DWARF Versions 3 and 4, note that DWARF V4
+\textit{In comparing 
+DWARF Versions 3 
+\addtoindexx{DWARF Version 3}
+and 
+\addtoindexx{DWARF Version 4}
+4, note that DWARF V4
 defines the following combinations of attributes:}
 
 \begin{itemize}
@@ -1346,11 +1418,15 @@ owned by the corresponding structure type entry.
 
 If the variant part has a discriminant, the discriminant is
 \hypertarget{chap:DWATdiscrdiscriminantofvariantpart}
-represented by a separate debugging information entry which
+represented by a 
+\addtoindexx{discriminant (entry)}
+separate debugging information entry which
 is a child of the variant part entry. This entry has the form
 of a structure data member entry. The variant part entry will
+\addtoindexx{discriminant attribute}
 have a 
-\livelink{chap:DWATdiscr}{DW\-\_AT\-\_discr} attribute whose value is a reference to
+\livelink{chap:DWATdiscr}{DW\-\_AT\-\_discr} attribute 
+whose value is a reference to
 the member entry for the discriminant.
 
 If the variant part does not have a discriminant (tag field),
@@ -1374,7 +1450,9 @@ an unsigned type.
 
 Alternatively, 
 \hypertarget{chap:DWATdiscrlistlistofdiscriminantvalues}
-the variant entry may contain a 
+the variant entry may contain 
+\addtoindexx{discriminant list attribute}
+a 
 \livelink{chap:DWATdiscrlist}{DW\-\_AT\-\_discr\-\_list}
 attribute, whose value represents a list of discriminant
 values. This list is represented by any of the 
@@ -1383,7 +1461,9 @@ may contain a mixture of case labels and label ranges. Each
 item on the list is prefixed with a discriminant value
 descriptor that determines whether the list item represents
 a single label or a label range. A single case label is
-represented as an LEB128 number as defined above for the
+represented as an LEB128 number as defined above for 
+\addtoindexx{discriminant value attribute}
+the
 \livelink{chap:DWATdiscrvalue}{DW\-\_AT\-\_discr\-\_value} 
 attribute. A label range is represented by
 two LEB128 numbers, the low value of the range followed by the
@@ -1737,8 +1817,14 @@ and upper bound values of the subrange. The
 \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}
 attribute 
 \hypertarget{chap:DWATcountelementsofsubrangetype}
-may be replaced by a 
-\livelink{chap:DWATcount}{DW\-\_AT\-\_count} attribute, whose
+may 
+% FIXME: The following matches DWARF4: odd as there is no default count.
+\addtoindexx{count attribute!default}
+be 
+\addtoindexx{count attribute}
+replaced by a 
+\livelink{chap:DWATcount}{DW\-\_AT\-\_count} attribute, 
+whose
 value describes the number of elements in the subrange rather
 than the value of the last element. The value of each of
 these attributes is determined as described in 
@@ -1771,7 +1857,8 @@ basis type, the basis type is assumed to be the same as
 the object described by the lower bound attribute (if it
 references an object). If there is no lower bound attribute,
 or that attribute does not reference an object, the basis type
-is the type of the upper bound or count attribute (if either
+is the type of the upper bound or \addtoindex{count attribute}
+(if either
 of them references an object). If there is no upper bound or
 count attribute, or neither references an object, the type is
 assumed to be the same type, in the source language of the