More pagination cleanups using \needspace and \needlines.
[dwarf-doc.git] / dwarf5 / latexdoc / programscope.tex
index 695bb74..cff986a 100644 (file)
@@ -130,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} \\
@@ -159,9 +159,9 @@ Language name & Meaning\\ \hline
 \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}\addtoindexx{UPC}\\ \hline
-\dag \ \ Support for these languages is limited.& \\
+\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 
@@ -214,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}
@@ -222,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
@@ -309,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.}
@@ -341,7 +337,7 @@ belong at the place of the imported unit entry.
 
 \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.}
 
@@ -368,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
@@ -465,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}
@@ -500,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
@@ -699,7 +696,7 @@ 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
@@ -708,13 +705,13 @@ being imported.
 
 \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
+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}.
 }
@@ -769,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}.
 
@@ -831,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
@@ -1060,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
@@ -1077,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
@@ -1125,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}
 
@@ -1233,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