Backup of today's work. Still awaiting a couple more editorial inputs.
[dwarf-doc.git] / dwarf5 / latexdoc / programscope.tex
index 30c5142..461c0e2 100644 (file)
@@ -81,9 +81,10 @@ unit may be logically incorporated into another compilation unit
 using an \addtoindex{imported unit entry}
 (see Section \refersec{chap:importedunitentries}).}
 
-\textit{A
-combined split and partial
-compilation unit kind is not defined.}
+\bb
+\textit{A partial compilation unit is not defined for use
+within a split object file.}
+\eb
 
 \textit{In the remainder of this document, the word 
 \doublequote{compilation} in the phrase \doublequote{compilation unit} 
@@ -132,7 +133,10 @@ in some cases.
 See Appendix \refersec{app:dwarfcompressionandduplicateeliminationinformative}
 for discussion of related compression techniques.}
 
-A compilation unit entry owns debugging information
+\bb
+A full or partial 
+\eb
+compilation unit entry owns debugging information
 entries that represent all or part of the declarations
 made in the corresponding compilation. In the case of a
 partial compilation unit, the containing scope of its owned
@@ -141,8 +145,10 @@ or more other compilation unit entries that refer to that
 partial compilation unit (see 
 Section \refersec{chap:importedunitentries}).
 
-Compilation unit entries may have the following 
-attributes:
+\bb
+A full or partial compilation unit entry 
+\eb
+may have the following attributes:
 \begin{enumerate}[1. ]
 \item Either a \DWATlowpc{} and 
 \DWAThighpc{} pair of
@@ -189,8 +195,10 @@ indicating the source language of the compilation
 unit. The set of language names and their meanings are given
 in Table \refersec{tab:languagenames}.
 
+\vspace{1cm}
+\needlines{8}
 \begin{centering}
-  \setlength{\extrarowheight}{0.1cm}
+\setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{l|l}
   \caption{Language names} \label{tab:languagenames} \\
   \hline \bfseries Language name & \bfseries Meaning \\ \hline
@@ -203,6 +211,10 @@ in Table \refersec{tab:languagenames}.
 \addtoindexx{ISO-defined language names}
 \DWLANGAdaeightythreeTARG{} \dag & ISO Ada:1983 \addtoindexx{Ada:1983 (ISO)} \\
 \DWLANGAdaninetyfiveTARG{}  \dag & ISO Ada:1995 \addtoindexx{Ada:1995 (ISO)} \\
+\bb
+\DWLANGBLISSTARG & BLISS \addtoindexx{BLISS}
+\eb
+\\
 \DWLANGCTARG & Non-standardized C, such as K\&R \addtoindexx{C!non-standard} \\*
 \DWLANGCeightynineTARG & ISO C:1989 \addtoindexx{C:1989 (ISO)} \\*
 \DWLANGCninetynineTARG & ISO C:1999 \addtoindexx{C:1999 (ISO)} \\*
@@ -234,7 +246,10 @@ in Table \refersec{tab:languagenames}.
 \DWLANGPascaleightythreeTARG & ISO Pascal:1983 \addtoindexx{Pascal:1983 (ISO)} \\
 \DWLANGPLITARG{}~\dag & ANSI PL/I:1976 \addtoindexx{PL/I:1976 (ANSI)} \\
 \DWLANGPythonTARG{}~\dag & \addtoindex{Python} \\
-\DWLANGRenderScriptTARG~\dag & \addtoindex{RenderScript Kernal Language}
+\DWLANGRenderScriptTARG~\dag & 
+\bb
+\addtoindex{RenderScript Kernel Language}
+\eb
 \\
 \DWLANGRustTARG{}~\dag & \addtoindex{Rust} \\
 \DWLANGSwiftTARG{}
@@ -418,7 +433,7 @@ This attribute points to the first string
 offset of the compilation unit's contribution to the
 \dotdebugstroffsets{} (or \dotdebugstroffsetsdwo{}) section. 
 Indirect string references
-(using \DWFORMstrx) within the compilation unit are
+(using \DWFORMstrxXNor) within the compilation unit are
 interpreted as indices relative to this base.
 
 \needlines{6}
@@ -427,9 +442,12 @@ A \DWATaddrbaseDEFN\addtoindexx{address table base attribute}
 attribute, whose value is of class \CLASSaddrptr.
 This attribute points to the beginning of the compilation
 unit's contribution to the \dotdebugaddr{} section.
-Indirect references (using \DWFORMaddrx, \DWOPaddrx, 
-\DWOPconstx, \DWLLEbaseaddressx{}, 
-\DWLLEstartxendx{} or \DWLLEstartxlength) 
+Indirect references (using \DWFORMaddrxXN, \DWOPaddrx, 
+\DWOPconstx, 
+\bb
+\DWLLEbaseaddressx{}, \DWLLEstartxendx{}, \DWLLEstartxlength{},
+\DWRLEbaseaddressx{}, \DWRLEstartxendx{} or \DWRLEstartxlength) 
+\eb
 within the compilation unit are interpreted as indices 
 relative to this base.
 
@@ -437,16 +455,24 @@ relative to this base.
 \item \hypertarget{chap:DWATrnglistsbaseforrnglists}{}
 A \DWATrnglistsbaseDEFN\addtoindexx{ranges table base attribute}
 attribute, whose value is of class \CLASSrnglistsptr.
-This attribute points to the base of the compilation
+This attribute points to the 
+\bb
+beginning of the offsets table (immediately following the header) 
+\eb
+of the compilation
 unit's contribution to the \dotdebugrnglists{} section.
 References to range lists (using \DWFORMrnglistx)
 within the compilation unit are
 interpreted relative to this base.
 
 \item \hypertarget{chap:DWATloclistsbaseinlocationlist}{}
-A \DWATloclistsbase{}\addtoindexx{location table base attribute} 
+A \DWATloclistsbaseDEFN{}\addtoindexx{location table base attribute} 
 attribute, whose value is of class \CLASSloclistsptr. 
-This attribute points to the base of the compilation 
+This attribute points to the 
+\bb
+beginning of the offsets table (immediately following the header) 
+\eb
+of the compilation 
 unit's contribution to the \dotdebugloclists{} section. References 
 to location lists (using \DWFORMloclistx) within the compilation 
 unit are interpreted relative to this base.
@@ -610,6 +636,7 @@ the sections in which they are represented
 Moreover, the \DWATstroffsetsbase{} attribute (see below) is not 
 used in a split type unit.
 
+\needlines{4}
 A type unit is represented by a debugging information entry
 with the tag \DWTAGtypeunitTARG. 
 A \addtoindex{type unit entry} owns debugging
@@ -664,7 +691,7 @@ attribute, whose value is of class \CLASSstroffsetsptr.
 This attribute points
 to the first string offset of the type unit's contribution to
 the \dotdebugstroffsets{} section. Indirect string references
-(using \DWFORMstrx) within the type unit are interpreted
+(using \DWFORMstrxXNor) within the type unit are interpreted
 as indices relative to this base.
 
 \end{enumerate}
@@ -676,6 +703,7 @@ namespaces, the debugging information entry for T is nested
 within debugging information entries describing its containers;
 otherwise, T is a direct child of the type unit entry.
 
+\needlines{4}
 A type unit entry may also own additional debugging information
 entries that represent declarations of additional types that
 are referenced by type T and have not themselves been placed in
@@ -739,6 +767,7 @@ If the module has a name, the module entry has a
 whose value is a null\dash terminated string containing
 the module name.
 
+\needlines{4}
 The \addtoindex{module entry} may have either a 
 \DWATlowpc{} and
 \DWAThighpc{} 
@@ -1014,10 +1043,10 @@ in Section \refersec{chap:importedorrenameddeclarationentries}.
 \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
-}
+to the original debugging information entry. For example, given}
+\par % Needed to end paragraph before listing so that it gets a line number
 \vspace{2mm}
-\begin{lstlisting}
+\begin{nlnlisting}
 module A
 integer X, Y, Z
 end module
@@ -1030,7 +1059,7 @@ module C
 use B, only Q => X
 end module
 
-\end{lstlisting}
+\end{nlnlisting}
 \textit{the imported declaration entry for Q within module C refers
 directly to the variable declaration entry for X in module A
 because there is no explicit representation for X in module B.
@@ -1078,6 +1107,7 @@ and entry
 \addtoindexx{entry point entry}
 points:
 
+\nolinenumbers
 \begin{tabular}{lp{9.0cm}}
 \DWTAGsubprogramTARG{} & A subroutine or function \\
 \DWTAGinlinedsubroutine{} & A particular inlined 
@@ -1085,7 +1115,7 @@ points:
 instance of a subroutine or function \\
 \DWTAGentrypointTARG{} & An alternate entry point \\
 \end{tabular}
-
+\par\condlinenumbers
 
 \needlines{6}
 \subsection{General Subroutine and Entry Point Information}
@@ -1272,6 +1302,7 @@ that has neither a \DWATcallpc{} nor \DWATcallreturnpc{} attribute.
 \textit{The \DWATcallallsourcecallsNAME{} attribute is intended for debugging 
 information format consumers that analyze call graphs.}
 
+\needlines{4}
 If the the \DWATcallallsourcecalls{} attribute is present then the 
 \DWATcallallcalls{} and \DWATcallalltailcalls{} attributes are 
 also implicitly present. Similarly, if the 
@@ -2504,8 +2535,8 @@ subsequent declaration.}
 
 \needlines{4}
 \textit{Consider the following example \addtoindex{C} code:}
-\vspace{3mm}
-\begin{lstlisting}
+\par % Needed to end paragraph before listing so that it gets a line number
+\begin{nlnlisting}
 float x = 99.99;
 int myfunc()
 {
@@ -2513,7 +2544,7 @@ int myfunc()
     float x = 88.99;
     return 0;
 }
-\end{lstlisting}
+\end{nlnlisting}
 
 \textit{\addtoindex{C} scoping rules require that the value of the 
 variable \texttt{x} assigned to the variable \texttt{f} in the