Misc corrections up thru Chpt 5
[dwarf-doc.git] / dwarf5 / latexdoc / programscope.tex
index 5407d19..695bb74 100644 (file)
@@ -9,12 +9,16 @@ as bounded by ranges of text addresses within the program.
 
 \section{Unit Entries}
 An object file may contain one or more compilation units,
-of which there are 
+of which there are
+\addtoindexx{unit|see {compilation unit, partial unit \textit{or} type unit}} 
 \addtoindexx{compilation unit}
 three kinds: 
 \addtoindexx{normal compilation unit}
+\addtoindexx{normal compilation unit|see {compilation unit}}
 normal compilation units,
-partial compilation units and type units. A 
+partial compilation units and 
+\addtoindexx{type unit}
+type units. A 
 \addtoindex{partial compilation unit}
 is related to one or more other compilation units that
 import it. A 
@@ -76,7 +80,6 @@ Section \refersec{chap:importedunitentries}).
 
 Compilation unit entries may have the following 
 attributes:
-
 \begin{enumerate}[1]
 \item Either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and 
 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of
@@ -94,7 +97,8 @@ the
 contiguous or 
 non\dash contiguous address ranges, respectively,
 of the machine instructions generated for the compilation
-unit (see Section {chap:codeaddressesandranges}).  
+unit (see Section \refersec{chap:codeaddressesandranges}).
+  
 A \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute 
 may also
 be specified 
@@ -154,15 +158,22 @@ Language name & Meaning\\ \hline
 \livetarg{chap:DWLANGPascal83}{DW\-\_LANG\-\_Pascal83} & ISO \addtoindex{Pascal}:1983\\
 \livetarg{chap:DWLANGPLI}{DW\-\_LANG\-\_PLI} \dag & ANSI \addtoindex{PL/I}:1976\\
 \livetarg{chap:DWLANGPython}{DW\-\_LANG\-\_Python} \dag & \addtoindex{Python}\\
-\livetarg{chap:DWLANGUPC}{DW\-\_LANG\-\_UPC} &\addtoindex{Unified Parallel C}\\ \hline
+\livetarg{chap:DWLANGUPC}{DW\-\_LANG\-\_UPC} &\addtoindex{Unified Parallel C}\addtoindexx{UPC}\\ \hline
 \dag \ \ Support for these languages is limited.& \\
 \end{tabular}
 \end{figure}
 
-\item A \livelink{chap:DWATstmtlist}{DW\-\_AT\-\_stmt\-\_list} attribute whose value is a section
+\item A \livelink{chap:DWATstmtlist}{DW\-\_AT\-\_stmt\-\_list}
+attribute whose value is 
+\addtoindexx{statement list attribute}
+a 
+\addtoindexx{section offset!in statement list attribute}
+section
 \hypertarget{chap:DWATstmtlistlinenumberinformationforunit}
 offset to the line number information for this compilation
-unit.  This information is placed in a separate object file
+unit.
+
+This information is placed in a separate object file
 section from the debugging information entries themselves. The
 value of the statement list attribute is the offset in the
 \addtoindex{.debug\_line} section of the first byte of the line number
@@ -171,7 +182,9 @@ information for this compilation unit
 
 \item A \livelink{chap:DWATmacroinfo}{DW\-\_AT\-\_macro\-\_info} attribute 
 \addtoindex{macro information attribute}
-whose value is a section
+whose value is a 
+\addtoindexx{section offset!in macro information attribute}
+section
 \hypertarget{chap:DWATmacroinfomacroinformation}
 offset to the macro information for this compilation unit.
 This information is placed in a separate object file section
@@ -274,7 +287,8 @@ to interpret a type conversion to a base type
 \hypertarget{chap:DWATuseUTF8compilationunitusesutf8strings}
 correctly.
 
-\item A \livelink{chap:DWATuseUTF8}{DW\-\_AT\-\_use\-\_UTF8} attribute, 
+\item A \livelink{chap:DWATuseUTF8}{DW\-\_AT\-\_use\-\_UTF8} attribute,
+\addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8} 
 which is a \livelink{chap:flag}{flag} whose
 presence indicates that all strings (such as the names of
 declared entities in the source program) are represented
@@ -325,24 +339,25 @@ whose value is a reference to the
 normal or partial compilation unit whose declarations logically
 belong at the place of the imported unit entry.
 
-An imported unit entry does not necessarily correspond to
+\textit{An imported unit entry does not necessarily correspond to
 any entity or construct in the source program. It is merely
 “glue” used to relate a partial unit, or a compilation
 unit used as a partial unit, to a place in some other
-compilation unit.
+compilation unit.}
 
 \subsection{Separate Type Unit Entries}
 \label{chap:separatetypeunitentries}
 An object file may contain any number of separate type
 unit entries, each representing a single complete type
-definition. Each type unit must be uniquely identified by
+definition. 
+Each \addtoindex{type unit} must be uniquely identified by
 a 64\dash bit signature, stored as part of the type unit, which
 can be used to reference the type definition from debugging
 information entries in other compilation units and type units.
 
 A type unit is represented by a debugging information entry
 with the tag \livetarg{chap:DWTAGtypeunit}{DW\-\_TAG\-\_type\-\_unit}. 
-A type unit entry owns debugging
+A \addtoindex{type unit entry} owns debugging
 information entries that represent the definition of a single
 type, plus additional debugging information entries that may
 be necessary to include as part of the definition of the type.
@@ -355,7 +370,7 @@ constant value is an integer code indicating the source
 language used to define the type. The set of language names
 and their meanings are given in Figure \refersec{fig:languagenames}.
 
-A type unit entry for a given type T owns a debugging
+A \addtoindex{type unit} entry for a given type T owns a debugging
 information entry that represents a defining declaration
 of type T. If the type is nested within enclosing types or
 namespaces, the debugging information entry for T is nested
@@ -376,14 +391,14 @@ U is a direct child of the type unit entry. The containing
 entries may be shared among the additional types and between
 T and the additional types.
 
-Types are not required to be placed in type units. In general,
+\textit{Types are not required to be placed in type units. In general,
 only large types such as structure, class, enumeration, and
 union types included from header files should be considered
 for separate type units. Base types and other small types
 are not usually worth the overhead of placement in separate
 type units. Types that are unlikely to be replicated, such
 as those defined in the main source file, are also better
-left in the main compilation unit.
+left in the main compilation unit.}
 
 \section{Module, Namespace and Importing Entries}
 \textit{Modules and namespaces provide a means to collect related
@@ -501,10 +516,14 @@ If a type, variable, or function declared in a namespace is
 defined outside of the body of the namespace declaration,
 that type, variable, or function definition entry has a
 \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute 
+\addtoindexx{specification attribute}
 whose value is a reference to the
 debugging information entry representing the declaration of
 the type, variable or function. Type, variable, or function
-entries with a \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute do not need
+entries with a 
+\livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute 
+\addtoindexx{specification attribute}
+do not need
 to duplicate information provided by the declaration entry
 referenced by the specification attribute.
 
@@ -523,6 +542,7 @@ reference to a namespace.}
 \textit{The \addtoindex{C++} 
 compilation unit specific ``unnamed namespace'' may
 \addtoindexx{namespace (C++)!unnamed}
+\addtoindexx{unnamed namespace|see {namespace (C++), unnamed}}
 be represented by a namespace entry with no name attribute in
 the original namespace declaration entry (and therefore no name
 attribute in any namespace extension entry of this namespace).
@@ -626,6 +646,7 @@ an imported entity, other than a namespace).
 
 \textit{A \addtoindex{Fortran} use statement 
 \addtoindexx{Fortran!use statement}
+\addtoindexx{use statement|see {Fortran, use statement}}
 with an ``only list'' may be
 represented by a series of imported declaration entries,
 one (or more) for each entity that is imported. An entity
@@ -666,10 +687,10 @@ name in that module. Any entity in the module that is not
 renamed in this way is known in the context of the imported
 module entry by the same name as it is declared in the module.
 
-\textit{A \addtoindex{C++} using directive 
-may be represented by an 
+\textit{A \addtoindex{C++} using directive
 \addtoindexx{namespace (C++)!using directive}
-imported module
+\addtoindexx{using directive|see {namespace (C++), using directive}} 
+may be represented by an imported module
 \hypertarget{chap:DWATimportnamespaceusingdirective}
 entry, with an import attribute referring to the namespace
 entry of the appropriate extension of the namespace (which
@@ -685,7 +706,8 @@ corresponding to those entities that are renamed as part of
 being imported.
 }
 
-\textit{A \addtoindex{Fortran} use statement 
+\textit{A \addtoindex{Fortran} use statement
+\addtoindexx{Fortran!use statement}
 with neither a “rename list” nor
 an “only list” may be represented by an imported module
 entry with an import attribute referring to the module and
@@ -698,10 +720,12 @@ in Section \refersec{chap:importedorrenameddeclarationentries}.
 }
 
 \textit{A \addtoindex{Fortran} use statement for an entity in a module that is
+\addtoindexx{Fortran!use statement}
 itself imported by a use statement without an explicit mention
 may be represented by an imported declaration entry that refers
 to the original debugging information entry. For example, given
 }
+
 \begin{lstlisting}
 module A
 integer X, Y, Z
@@ -716,15 +740,18 @@ use B, only Q => X
 end module
 \end{lstlisting}
 
-the imported declaration entry for Q within module C refers
+\textit{the imported declaration entry for Q within module C refers
 directly to the variable declaration entry for A in module A
 because there is no explicit representation for X in module B.
+}
 
-A similar situation arises for a \addtoindex{C++} using declaration that
-imports an entity in terms of a namespace alias. See 
+\textit{A similar situation arises for a \addtoindex{C++} using declaration
+\addtoindexx{namespace (C++)!using declaration}
+\addtoindexx{using declaration|see {namespace (C++), using declaration}}
+that imports an entity in terms of a namespace alias. See 
 Appendix  \refersec{app:namespaceexample}
 for an example.
-
+}
 
 \section{Subroutine and Entry Point Entries}
 \label{chap:subroutineandentrypointentries}
@@ -734,7 +761,9 @@ debugging information entries
 \addtoindexx{function entry|see{subroutine entry}}
 for 
 \addtoindexx{subroutine entry}
-subroutines and entry
+subroutines 
+\addtoindexx{subprogram entry}
+and entry
 % FIXME: is entry point entry the right index 'entry'?
 \addtoindexx{entry point entry}
 points:
@@ -754,6 +783,7 @@ It may also have a \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name}
 described in Section \refersec{chap:linkagenames}.
 
 If the name of the subroutine described by an entry with the
+\addtoindex{subprogram entry}
 tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
 is visible outside of its containing
 \hypertarget{chap:DWATexternalexternalsubroutine}
@@ -875,7 +905,7 @@ or property.
 A 
 \hypertarget{chap:DWATpurepurepropertyofasubroutine}
 subprogram entry may have 
-\addtoindexx{pure attrubyte}
+\addtoindexx{pure attribute}
 a 
 \livelink{chap:DWATpure}{DW\-\_AT\-\_pure} attribute, which is
 a \livelink{chap:flag}{flag}. 
@@ -901,8 +931,10 @@ If
 the subroutine or entry point 
 \addtoindexx{return type of subroutine}
 is a function that returns a
-value, then its debugging information entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type}
-attribute to denote the type returned by that function.
+value, then its debugging information entry has 
+\addtoindexx{type attribute}
+a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute 
+to denote the type returned by that function.
 
 \textit{Debugging information entries for 
 \addtoindex{C} void functions should
@@ -1074,7 +1106,8 @@ debuggers to support this same kind of referencing.}
 If 
 \hypertarget{chap:DWATstaticlinklocationofuplevelframe}
 a 
-\addtoindexx{address!uplevel|see{static link attribute}}
+\addtoindexx{address!uplevel|see {static link attribute}}
+\addtoindexx{uplevel address|see {static link attribute}}
 subroutine or entry point is nested, it may have a
 \livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link}
 attribute, whose value is a location
@@ -1113,14 +1146,18 @@ it may validly throw.}
 
 If a subroutine explicitly declares that it may throw
 \addtoindexx{exception thrown|see{thrown type entry}}
-an exception for one or more types, each such type is
+an 
+\addtoindexx{thrown exception|see{thrown type entry}}
+exception for one or more types, each such type is
 represented by a debugging information entry with 
 \addtoindexx{thrown type entry}
 the tag
 \livetarg{chap:DWTAGthrowntype}{DW\-\_TAG\-\_thrown\-\_type}.  
 Each such entry is a child of the entry
 representing the subroutine that may throw this type. Each
-thrown type entry contains a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute, whose
+thrown type entry contains 
+\addtoindexx{type attribute}
+a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute, whose
 value is a reference to an entry describing the type of the
 exception that may be thrown.
 
@@ -1132,8 +1169,11 @@ a function that is instantiated differently when called with
 values of different types. DWARF does not represent the generic
 template definition, but does represent each instantiation.}
 
-A template instantiation is represented by a debugging
-information entry with the tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}. With four
+A \addtoindex{template instantiation} is represented by a debugging
+information entry with the 
+\addtoindexx{subprogram entry!use for template instantiation}
+tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}. 
+With four
 exceptions, such an entry will contain the same attributes and
 will have the same types of child entries as would an entry
 for a subroutine defined explicitly using the instantiation
@@ -1143,6 +1183,7 @@ types. The exceptions are:
 \item Each formal parameterized type declaration appearing in the
 template definition is represented by a debugging information
 entry with the 
+\addtoindexx{template type parameter entry}
 tag \livetarg{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}. 
 Each
 such entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, 
@@ -1151,7 +1192,9 @@ whose value is a
 null\dash terminated string containing the name of the formal
 type parameter as it appears in the source program. The
 \addtoindexx{formal type parameter|see{template type parameter entry}}
-template type parameter entry also has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute
+template type parameter entry also has 
+\addtoindexx{type attribute}
+a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute
 describing the actual type by which the formal is replaced
 for this instantiation.
 
@@ -1180,7 +1223,9 @@ A declaration or a definition of an inlinable subroutine
 is represented by a debugging information entry with the
 tag 
 \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}.
-The entry for a subroutine that is
+The entry for a 
+\addtoindexx{subprogram entry!use in inlined subprogram}
+subroutine that is
 \hypertarget{chap:DWATinlineinlinedsubroutine}
 explicitly declared to be available for inline expansion or
 that was expanded inline implicitly by the compiler has 
@@ -1196,8 +1241,8 @@ Figure \refersec{fig:inlinecodes}.
 \label{fig:inlinecodes}
 \begin{tabular}{lp{9cm}}
 Name&Meaning\\ \hline
-\livetarg{chap:DWINLnotinlined}{DW\-\_INL\-\_not\-\_inlined} & Not delared inline nor inlined by the
-  compiler(equivalent to the absense of the containing
+\livetarg{chap:DWINLnotinlined}{DW\-\_INL\-\_not\-\_inlined} & Not declared inline nor inlined by the
+  compiler(equivalent to the absence of the containing
   \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute) \\
 \livetarg{chap:DWINLinlined}{DW\-\_INL\-\_inlined} & Not declared inline but inlined by the compiler \\
 \livetarg{chap:DWINLdeclarednotinlined}{DW\-\_INL\-\_declared\-\_not\-\_inlined} & Declared inline but 
@@ -1213,7 +1258,7 @@ entry with the tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}. Suc
 \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute whose value is \livelink{chap:DWINLinlined}{DW\-\_INL\-\_inlined}.}
 
 
-\paragraph{Abstract Instances}
+\subsubsection{Abstract Instances}
 \label{chap:abstractinstances}
 Any debugging information entry that is owned (either
 \hypertarget{chap:DWATinlineabstracttinstance}
@@ -1243,8 +1288,11 @@ instance tree.
 
 Each abstract instance root is either part of a larger
 \addtoindexx{abstract instance!root}
-tree (which gives a context for the root) or uses
-\livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} to refer to the declaration in context.
+tree (which gives a context for the root) or 
+\addtoindexx{specification attribute}
+uses
+\livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} 
+to refer to the declaration in context.
 
 \textit{For example, in \addtoindex{C++} the context might be a namespace
 declaration or a class declaration.}
@@ -1275,6 +1323,7 @@ should
 be 
 \addtoindexx{low PC attribute!and abstract instance}
 omitted; 
+\addtoindex{segment attribute!and abstract instance}
 however, 
 \addtoindexx{return address attribute!and abstract instance}
 this 
@@ -1300,7 +1349,7 @@ entries. Also, the ordering rules for formal parameter entries,
 member entries, and so on, all apply regardless of whether
 or not a given entry is abstract.
 
-\paragraph{Concrete Inlined Instances}
+\subsubsection{Concrete Inlined Instances}
 \label{chap:concreteinlinedinstances}
 
 Each inline expansion of a subroutine is represented
@@ -1358,9 +1407,10 @@ the same way as the declaration file, declaration line, and
 declaration column attributes, respectively (see 
 Section \refersec{chap:declarationcoordinates}).
 
-The call file, call line and call column coordinates do not
+\textit{The call file, call line and call column coordinates do not
 describe the coordinates of the subroutine declaration that
 was inlined, rather they describe the coordinates of the call.
+}
 
 An inlined subroutine entry 
 \hypertarget{chap:DWATconstexprcompiletimeconstantfunction}
@@ -1497,7 +1547,7 @@ entries can be described in its concrete inlined instance tree.
 
 \end{enumerate}
 
-\paragraph{Out-of-Line Instances of Inlined Subroutines}
+\subsubsection{Out-of-Line Instances of Inlined Subroutines}
 \label{chap:outoflineinstancesofinlinedsubroutines}
 Under some conditions, compilers may need to generate concrete
 executable instances of inlined subroutines other than at
@@ -1546,7 +1596,7 @@ trees be owned by the same parent entry.
 
 \end{enumerate}
 
-\paragraph{Nested Inlined Subroutines}
+\subsubsection{Nested Inlined Subroutines}
 \label{nestedinlinedsubroutines}
 Some languages and compilers may permit the logical nesting of
 a subroutine within another subroutine, and may permit either
@@ -1609,8 +1659,12 @@ adjust parameters and/or the result (if any) as appropriate
 to the combined calling and called execution contexts.}
 
 A trampoline is represented by a debugging information entry
+\addtoindexx{trampoline (subprogam) entry}
 with the tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} or \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
-that has a \livelink{chap:DWATtrampoline}{DW\-\_AT\-\_trampoline} attribute. The value of that
+that has 
+\addtoindexx{trampoline attribute}
+a \livelink{chap:DWATtrampoline}{DW\-\_AT\-\_trampoline} attribute. 
+The value of that
 attribute indicates the target subroutine of the trampoline,
 that is, the subroutine to which the trampoline passes
 control. (A trampoline entry may but need not also have a
@@ -1645,8 +1699,10 @@ subprogram.)
 \textit{In \addtoindex{C++}, trampolines may be used 
 to implement derived virtual
 member functions; such trampolines typically adjust the
+\addtoindexx{this parameter}
 implicit this pointer parameter in the course of passing
-control.  Other languages and environments may use trampolines
+control.  
+Other languages and environments may use trampolines
 in a manner sometimes known as transfer functions or transfer
 vectors.}
 
@@ -1680,14 +1736,13 @@ that may contain any number of declarations. In some languages
 \nolink{blocks} can be nested within other
 \nolink{blocks} to any depth.}
 
-% We do not need to link to the preceeding paragraph.
+% We do not need to link to the preceding paragraph.
 A lexical \nolink{block} is represented by a debugging information
 entry with the 
 tag \livetarg{chap:DWTAGlexicalblock}{DW\-\_TAG\-\_lexical\-\_block}.
 
 The lexical \livetargi{chap:lexicalblockentry}{block}{lexical block entry} 
-entry
-may have 
+entry may have 
 either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
 \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of 
 attributes 
@@ -1726,10 +1781,10 @@ of an identifier or inner lexical \livelink{chap:lexicalblock}{block}.
 
 \section{Label Entries}
 \label{chap:labelentries}
-
-A label is a way of identifying a source statement. A labeled
+\textit{A label is a way of identifying a source statement. A labeled
 statement is usually the target of one or more ``go to''
 statements.
+}
 
 A label is represented by a debugging information entry with
 \addtoindexx{label entry}
@@ -1778,7 +1833,9 @@ ranges, respectively, of the machine instructions generated
 for the with statement 
 (see Section \refersec{chap:codeaddressesandranges}).
 
-The with statement entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute, denoting
+The with statement entry has 
+\addtoindexx{type attribute}
+a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute, denoting
 the type of record whose fields may be referenced without full
 qualification within the body of the statement. It also has
 \addtoindexx{location attribute}
@@ -1801,9 +1858,11 @@ can handle.}
 
 A try \livetargi{chap:tryblock}{block}{try block} is represented 
 by a debugging information entry
+\addtoindexx{try block entry}
 with the tag \livetarg{chap:DWTAGtryblock}{DW\-\_TAG\-\_try\-\_block}.  
 A catch \livelink{chap:catchblock}{block} is represented by
 a debugging information entry with 
+\addtoindexx{catch block entry}
 the tag \livetarg{chap:DWTAGcatchblock}{DW\-\_TAG\-\_catch\-\_block}.
 
 % nolink as we have links just above and do not have a combo link for both
@@ -1826,7 +1885,6 @@ Catch \livelink{chap:catchblock}{block} entries have at
 least one child entry, an
 entry representing the type of exception accepted by
 that catch \livelink{chap:catchblock}{block}. 
-
 This child entry has one of 
 \addtoindexx{formal parameter entry!in catch block}
 the