More pagination cleanups using \needspace and \needlines.
[dwarf-doc.git] / dwarf5 / latexdoc / programscope.tex
index bab5c0b..cff986a 100644 (file)
@@ -9,10 +9,12 @@ 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 
 \addtoindexx{type unit}
@@ -78,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
@@ -96,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 
@@ -128,14 +130,14 @@ integer code
 \addtoindexx{language attribute}
 indicating the source language of the compilation
 unit. The set of language names and their meanings are given
-in 
-Figure \refersec{fig:languagenames}.
+in Table \refersec{tab:languagenames}.
 
-\begin{figure}[here]
+\begin{table}[here]
 \centering
 \caption{Language names}
-\label{fig:languagenames}
-\begin{tabular}{ll}
+\label{tab:languagenames}
+\begin{tabular}{l|l}
+\hline
 Language name & Meaning\\ \hline
 \livetarg{chap:DWLANGAda83}{DW\-\_LANG\-\_Ada83} \dag&ISO \addtoindex{Ada}:1983 \addtoindexx{Ada} \\
 \livetarg{chap:DWLANGAda95}{DW\-\_LANG\-\_Ada95} \dag&ISO Ada:1995 \addtoindexx{Ada} \\
@@ -156,20 +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
-\dag \ \ Support for these languages is limited.& \\
+\livetarg{chap:DWLANGUPC}{DW\-\_LANG\-\_UPC} &\addtoindex{Unified Parallel C}\addtoindexx{UPC}\\ \hline
+\dag \ \ \textit{Support for these languages is limited.}& \\
 \end{tabular}
-\end{figure}
+\end{table}
 
-\item A \livelink{chap:DWATstmtlist}{DW\-\_AT\-\_stmt\-\_list} attribute whose value is 
+\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
+offset to the line number information for this compilation
+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
@@ -210,7 +214,7 @@ begin with the name of the compiler vendor or some other
 identifying character sequence that should avoid confusion
 with other producer values.
 
-
+\needlines{4}
 \item  A \livelink{chap:DWATidentifiercase}{DW\-\_AT\-\_identifier\-\_case} 
 attribute 
 \addtoindexx{identifier case attribute}
@@ -218,19 +222,15 @@ whose integer
 \hypertarget{chap:DWATidentifiercaseidentifiercaserule}
 constant value is a code describing the treatment
 of identifiers within this compilation unit. The
-set of identifier case codes 
-is given in Figure
-\refersec{fig:identifiercasecodes}.
-
-\begin{figure}[here]
-\autorows[0pt]{c}{1}{l}{
-\livelink{chap:DWIDcasesensitive}{DW\-\_ID\-\_case\-\_sensitive},
-\livelink{chap:DWIDupcase}{DW\-\_ID\-\_up\-\_case},
-\livelink{chap:DWIDdowncase}{DW\-\_ID\-\_down\-\_case},
-\livelink{chap:DWIDcaseinsensitive}{DW\-\_ID\-\_case\-\_insensitive}
-}
-\caption{Identifier case codes}\label{fig:identifiercasecodes}
-\end{figure}
+set of identifier case codes is given in
+Table \refersec{tab:identifiercasecodes}.
+
+\begin{simplenametable}{Identifier case codes}{tab:identifiercasecodes}
+\livelink{chap:DWIDcasesensitive}{DW\-\_ID\-\_case\-\_sensitive}        \\
+\livelink{chap:DWIDupcase}{DW\-\_ID\-\_up\-\_case}                      \\
+\livelink{chap:DWIDdowncase}{DW\-\_ID\-\_down\-\_case}                  \\
+\livelink{chap:DWIDcaseinsensitive}{DW\-\_ID\-\_case\-\_insensitive}    \\
+\end{simplenametable}
 
 \livetarg{chap:DWIDcasesensitive}{DW\-\_ID\-\_case\-\_sensitive} is the default for all compilation units
 that do not have this attribute.  It indicates that names given
@@ -283,7 +283,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
@@ -304,7 +305,7 @@ this \nolink{flag}, any one of them may contain the starting function.
 which is used
 to specify and provide a user\dash specified name for the main
 subroutine of a program. 
-\addtoindex{C} uses the name “main” to identify
+\addtoindex{C} uses the name \doublequote{main} to identify
 the main subprogram of a program. Some other languages provide
 similar or other means to identify the main subprogram of
 a program.}
@@ -334,11 +335,11 @@ 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
+\doublequote{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}
@@ -363,7 +364,7 @@ whose
 \addtoindexx{language attribute}
 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}.
+and their meanings are given in Table \refersec{tab:languagenames}.
 
 A \addtoindex{type unit} entry for a given type T owns a debugging
 information entry that represents a defining declaration
@@ -386,14 +387,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
@@ -460,7 +461,7 @@ a
 The value of this attribute is a
 reference to another debugging information entry describing
 a variable with a constant value. The value of this variable
-is the actual constant value of the modules priority,
+is the actual constant value of the module\textquoteright s priority,
 represented as it would be on the target architecture.
 
 \subsection{Namespace Entries}
@@ -495,6 +496,7 @@ a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute
 need only be attached directly to the original
 \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} entry.)
 
+\needlines{4}
 Namespace and namespace extension entries may own 
 \addtoindexx{namespace extension entry}
 other
@@ -537,6 +539,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).
@@ -640,6 +643,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
@@ -680,10 +684,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
@@ -692,30 +696,33 @@ might be the original namespace entry) and no owned entries.
 
 \textit{A \addtoindex{Fortran} use statement 
 \addtoindexx{Fortran!use statement}
-with a “rename list” may be
+with a \doublequote{rename list} may be
 represented by an imported module entry with an import
 attribute referring to the module and owned entries
 corresponding to those entities that are renamed as part of
 being imported.
 }
 
-\textit{A \addtoindex{Fortran} use statement 
-with neither a “rename list” nor
-an “only list” may be represented by an imported module
+\textit{A \addtoindex{Fortran} use statement
+\addtoindexx{Fortran!use statement}
+with neither a \doublequote{rename list} nor
+an \doublequote{only list} may be represented by an imported module
 entry with an import attribute referring to the module and
 no owned child entries.
 }
 
-\textit{A use statement with an “only list” is represented by a
+\textit{A use statement with an \doublequote{only list} is represented by a
 series of individual imported declaration entries as described
 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
@@ -730,15 +737,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}
@@ -756,16 +766,18 @@ and entry
 points:
 
 \begin{tabular}{lp{9.0cm}}
-\livetarg{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} & A subroutine or function. \\
+\livetarg{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} & A subroutine or function \\
 \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine} & A particular inlined 
 \addtoindexx{inlined subprogram entry}
-instance of a subroutine or function. \\
-\livetarg{chap:DWTAGentrypoint}{DW\-\_TAG\-\_entry\-\_point} & An alternate entry point. \\
+instance of a subroutine or function \\
+\livetarg{chap:DWTAGentrypoint}{DW\-\_TAG\-\_entry\-\_point} & An alternate entry point \\
 \end{tabular}
 
 \subsection{General Subroutine and Entry Point Information}
 \label{chap:generalsubroutineandentrypointinformation}
-
+The subroutine or entry point entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} 
+attribute whose value is a null-terminated string containing the 
+subroutine or entry point name as it appears in the source.
 It may also have a \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} attribute as
 described in Section \refersec{chap:linkagenames}.
 
@@ -818,16 +830,13 @@ contain a
 \livelink{chap:DWATcallingconvention}{DW\-\_AT\-\_calling\-\_convention}
 attribute, whose value is an integer constant. The set of
 calling convention codes is given in 
-Figure \refersec{fig:callingconventioncodes}.
+Table \refersec{tab:callingconventioncodes}.
 
-\begin{figure}[here]
-\autorows[0pt]{c}{1}{l}{
-\addtoindex{DW\-\_CC\-\_normal},
-\addtoindex{DW\-\_CC\-\_program},
-\addtoindex{DW\-\_CC\-\_nocall},
-}
-\caption{Calling convention codes}\label{fig:callingconventioncodes}
-\end{figure}
+\begin{simplenametable}[1.4in]{Calling convention codes}{tab:callingconventioncodes}
+\addtoindex{DW\-\_CC\-\_normal}        \\
+\addtoindex{DW\-\_CC\-\_program}       \\
+\addtoindex{DW\-\_CC\-\_nocall}        \\
+\end{simplenametable}
 
 If this attribute is not present, or its value is the constant
 \livetarg{chap:DWCCnormal}{DW\-\_CC\-\_normal}, then the subroutine may be safely called by
@@ -1047,7 +1056,7 @@ subroutine or entry point entry may also have
 \addtoindexx{frame base attribute}
 a
 \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute, whose value is a location
-description that computes the “frame base” for the
+description that computes the \doublequote{frame base} for the
 subroutine or entry point. If the location description is
 a simple register location description, the given register
 contains the frame base address. If the location description is
@@ -1064,17 +1073,17 @@ context is equivalent to using
 but more
 compact. However, these are not equivalent in general.}
 
+\needlines{5}
 \textit{The frame base for a procedure is typically an address fixed
 relative to the first unit of storage allocated for the
-procedures stack frame. The \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute
+procedure\textquoteright s stack frame. The \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute
 can be used in several ways:}
-
 \begin{enumerate}[1.]
 \item \textit{In procedures that need 
 \addtoindexx{location list}
 location lists to locate local
 variables, the \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} can hold the needed location
-list, while all variables location descriptions can be
+list, while all variables\textquoteright\  location descriptions can be
 simpler ones involving the frame base.}
 
 \item \textit{It can be used in resolving ``up\dash level'' addressing
@@ -1093,7 +1102,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
@@ -1111,7 +1121,7 @@ life of the procedure, and
 
 \item The computed value should be unique among instances of
 the same subroutine. (For typical \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} use, this
-means that a recursive subroutines stack frame must have
+means that a recursive subroutine\textquoteright s stack frame must have
 non\dash zero size.)
 \end{enumerate}
 
@@ -1135,7 +1145,6 @@ If a subroutine explicitly declares that it may throw
 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
@@ -1220,23 +1229,25 @@ that was expanded inline implicitly by the compiler has
 a
 \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute whose value is an integer constant. The
 set of values for the \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute is given in
-Figure \refersec{fig:inlinecodes}.
+Table \refersec{tab:inlinecodes}.
 
-\begin{figure}[here]
+\begin{table}[here]
 \centering
 \caption{Inline codes}
-\label{fig:inlinecodes}
-\begin{tabular}{lp{9cm}}
+\label{tab:inlinecodes}
+\begin{tabular}{l|p{9cm}}
+\hline
 Name&Meaning\\ \hline
 \livetarg{chap:DWINLnotinlined}{DW\-\_INL\-\_not\-\_inlined} & Not declared inline nor inlined by the
-  compiler(equivalent to the absence of the containing
+  compiler (equivalent to the absence of the containing \break
   \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 
   not inlined by the compiler \\
 \livetarg{chap:DWINLdeclaredinlined}{DW\-\_INL\-\_declared\-\_inlined} & Declared inline and inlined by the compiler \\
+\hline
 \end{tabular}
-\end{figure}
+\end{table}
 
 \textit{In \addtoindex{C++}, a function or a constructor declared with
 constexpr is implicitly declared inline. The abstract inline
@@ -1245,7 +1256,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}
@@ -1336,7 +1347,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
@@ -1394,9 +1405,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}
@@ -1533,7 +1545,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
@@ -1582,7 +1594,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
@@ -1728,8 +1740,7 @@ 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 
@@ -1768,10 +1779,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}
@@ -1872,7 +1883,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