More pagination cleanups using \needspace and \needlines.
[dwarf-doc.git] / dwarf5 / latexdoc / examples.tex
index ec9226d..f6307cf 100644 (file)
@@ -38,7 +38,7 @@ typedef char* strp;
 %\centering
 \begin{minipage}{0.4\textwidth}
 \centering
-Compilation Unit 1: \addtoindex{.debug\_info}
+Compilation Unit \#1: \addtoindex{.debug\_info}
 \begin{framed}
 \scriptsize
 \begin{alltt}
@@ -60,7 +60,7 @@ Compilation Unit 1: \addtoindex{.debug\_info}
 \vspace{0.01cm}
 \hrule
 2
-“char”
+\doublequote{char}
 \livelink{chap:DWATEunsignedchar}{DW\-\_ATE\-\_unsigned\-\_char}
 1
 \vspace{0.01cm}
@@ -70,7 +70,7 @@ e1
 \vspace{0.01cm}
 \hrule
 4
-“POINTER”
+\doublequote{POINTER}
 e2
 \vspace{0.01cm}
 \hrule
@@ -79,7 +79,7 @@ e2
 %
 %
 \end{framed}
-Compilation Unit 2: \addtoindex{.debug\_info}
+Compilation Unit \#2: \addtoindex{.debug\_info}
 \begin{framed}
 \scriptsize
 \begin{alltt}
@@ -93,7 +93,7 @@ Compilation Unit 2: \addtoindex{.debug\_info}
 \vspace{0.01cm}
 \hrule
 4
-“strp”
+\doublequote{strp}
 e2
 \vspace{0.01cm}
 \hrule
@@ -230,7 +230,7 @@ struct desc {
 \end{figure}
 
 
-In practice, of course, a “real” descriptor will have
+In practice, of course, a \doublequote{real} descriptor will have
 dimension substructures only for as many dimensions as are
 specified in the num\_dims component. Let us use the notation
 \texttt{desc\textless n\textgreater}   
@@ -240,16 +240,16 @@ contents of the num\_dims component.
 
 Because the arrays considered here come in two parts, it is
 necessary to distinguish the parts carefully. In particular,
-the “address of the variable” or equivalently, the “base
-address of the object \emph{always} refers to the descriptor. For
+the \doublequote{address of the variable} or equivalently, the \doublequote{base
+address of the object} \emph{always} refers to the descriptor. For
 arrays that do not come in two parts, an implementation can
 provide a descriptor anyway, thereby giving it two parts. (This
 may be convenient for general runtime support unrelated to
 debugging.) In this case the above vocabulary applies as
 stated. Alternatively, an implementation can do without a
-descriptor, in which case the “address of the variable”,
-or equivalently the “base address of the object”, refers
-to the “raw data” (the real data, the only thing around
+descriptor, in which case the \doublequote{address of the variable},
+or equivalently the \doublequote{base address of the object}, refers
+to the \doublequote{raw data} (the real data, the only thing around
 that can be the object).
 
 If an object has a descriptor, then the DWARF type for that
@@ -295,7 +295,8 @@ The DWARF description is shown
 \addtoindexx{Fortran 90}
 in Figure \refersec{fig:fortran90exampledwarfdescription}.
 
-\begin{figure}[b]
+\begin{figure}[h]
+\figurepart{1}{2}
 \begin{dwflisting}
 \begin{alltt}
 ! Description for type of 'ap'
@@ -315,15 +316,6 @@ in Figure \refersec{fig:fortran90exampledwarfdescription}.
             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == offset(base)
             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref}) ! Type of index of array 'ap'
-\end{alltt}
-\end{dwflisting}
-\caption{Fortran 90 example: DWARF description}
-\label{fig:fortran90exampledwarfdescription}
-\end{figure}
-
-\begin{figure}
-\begin{dwflisting}
-\begin{alltt}
 2\$: \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
         ! No name, default stride
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
@@ -348,6 +340,16 @@ in Figure \refersec{fig:fortran90exampledwarfdescription}.
         !                 offset(dims\_str, [lower|upper]\_bound)
         !  That is, the expression does not get longer for each successive 
         !  dimension (other than to express the larger offsets involved).
+\end{alltt}
+\end{dwflisting}
+\caption{Fortran 90 example: DWARF description}
+\label{fig:fortran90exampledwarfdescription}
+\end{figure}
+
+\begin{figure}
+\figurepart{2}{2}
+\begin{dwflisting}
+\begin{alltt}
 3\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("array\_ptr")
         \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}(constant sizeof(REAL) + sizeof(desc<1>))
@@ -371,22 +373,11 @@ in Figure \refersec{fig:fortran90exampledwarfdescription}.
             \livetarg{chap:DWOPlit2}{DW\-\_OP\-\_lit2}
             ! Mask for 'ptr\_alloc' \nolink{flag}
             \livelink{chap:DWOPand}{DW\-\_OP\-\_and})
-\end{alltt}
-\end{dwflisting}
-\begin{center}
-Figure~\ref{fig:fortran90exampledwarfdescription} Fortran 90 example: DWARF description \textit{(continued)}
-\end{center}
-\end{figure}
-
-\begin{figure}
-\begin{dwflisting}
-\begin{alltt}
         \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}(expression= ! Get raw data address
             \livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address}
             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n = offset(base)
             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref})
-
 7\$: \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
         ! No name, default stride
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
@@ -400,7 +391,6 @@ Figure~\ref{fig:fortran90exampledwarfdescription} Fortran 90 example: DWARF desc
             \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == ...
             \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus}
             \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref})
-
 8\$: \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("arrays")
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 6\$)
@@ -469,6 +459,8 @@ For c), the default stride applies. Since there is no
 \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride} attribute, use the size of the array element
 type, which is the size of type array\_ptr (at 3\$).
 
+\clearpage
+
 Having acquired all the necessary data, perform the indexing
 operation in the usual manner -  which has nothing to do with
 any of the attributes involved up to now. Those just provide
@@ -495,7 +487,7 @@ several pieces of information:
 \item  the lower bounds of the array \\
 % Using plain [] here gives trouble.
 \lbrack To check that 2 is within bounds we would require the upper
-%bound too, but well skip that for this example \rbrack
+%bound too, but we\textquoteright ll skip that for this example \rbrack
 
 \item  the stride
 
@@ -630,7 +622,7 @@ of this example and therefore not shown.
                 \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(reference to member N at 27\$)
 30\$:   \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("VEC2")
-            \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to array “subtype” at 28\$)
+            \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to array \doublequote{subtype} at 28\$)
             \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location}(machine=
                 \livelink{chap:DWOPlit}{DW\-\_OP\-\_lit}<n> ! where n == offset(REC2, VEC2)
                 \livelink{chap:DWOPplus}{DW\-\_OP\-\_plus})
@@ -757,7 +749,7 @@ namespace A {
     namespace B {
         int j;
         int myfunc (int a);
-        float myfunc (float f) { return f  2.0; }
+        float myfunc (float f) { return f \textendash 2.0; }
         int myfunc2(int a) { return a + 2; }
     }
 }
@@ -886,6 +878,9 @@ Figure~\ref{fig:namespaceexampledwarfdescription}: Namespace example: DWARF desc
 
 Consider the member function example fragment in 
 Figure \refersec{fig:memberfunctionexamplesourcefragment}.
+The DWARF representation in 
+Figure \refersec{fig:memberfunctionexampledwarfdescription}
+is appropriate.
 
 \begin{figure}[Here]
 \begin{lstlisting}
@@ -901,10 +896,6 @@ void A::func1(int x) {}
 \label{fig:memberfunctionexamplesourcefragment}
 \end{figure}
 
-The DWARF representation in 
-Section \refersec{fig:memberfunctionexampledwarfdescription}
-is appropriate.
-
 \begin{figure}[h]
 \begin{dwflisting}
 \begin{alltt}
@@ -1053,7 +1044,7 @@ of n).
 \newpage
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
-\begin{longtable}{lll}
+\begin{longtable}{l|l|l}
   \caption{Line number program example: one encoding}
   \label{tab:linenumberprogramexampleoneencoding} \\
   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
@@ -1084,7 +1075,7 @@ this encoding occupies 22 bytes.
 
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
-\begin{longtable}{lll}
+\begin{longtable}{l|l|l}
   \caption{Line number program example: alternate encoding} 
   \label{tab:linenumberprogramexamplealternateencoding} \\
   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
@@ -1197,7 +1188,7 @@ Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
 
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
-\begin{longtable}{lllllllllll}
+\begin{longtable}{l|llllllllll}
   \caption{Call frame information example: conceptual matrix} 
   \label{tab:callframeinformationexampleconceptualmatrix} \\
   \hline \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
@@ -1223,12 +1214,14 @@ foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
 \end{longtable}
 \end{centering}
 
+\clearpage      % ?????
 
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
-\begin{longtable}{lll}
+\begin{longtable}{l|ll}
   \caption{Call frame information example: common information entry encoding} 
-  \label{tab:callframeinformationexamplecommoninformationentryencoding} \\
+  \label{tab:callframeinformationexamplecommoninformationentryencoding} 
+  \\
   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
 \endfirsthead
   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
@@ -1276,7 +1269,7 @@ Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
 
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
-\begin{longtable}{lll}
+\begin{longtable}{l|ll}
   \caption{Call frame information example: frame description entry encoding} 
   \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
@@ -1293,15 +1286,15 @@ fde+8&foo&initial\_location \\
 fde+12&84&address\_range \\
 fde+16&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)&instructions \\
 fde+17&\livelink{chap:DWCFAdefcfaoffset}{DW\-\_CFA\-\_def\-\_cfa\-\_offset}(12)& \textless fs\textgreater \\
-fde+19&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)&4/ \textless caf\textgreater \\
-fde+20&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(8,1)&-4/ \textless daf\textgreater (2nd parameter) \\
+fde+19&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)&4/\textless caf\textgreater \\
+fde+20&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(8,1)&-4/\textless daf\textgreater (2nd parameter) \\
 fde+22&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1)& \\
-fde+23&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(6,2)&-8/ \textless daf\textgreater (2nd parameter)  \\
+fde+23&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(6,2)&-8/\textless daf\textgreater (2nd parameter)  \\
 fde+25&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) & \\
 fde+26&\livelink{chap:DWCFAdefcfaregister}{DW\-\_CFA\-\_def\-\_cfa\-\_register}(6) & \\
 fde+28&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) & \\
-fde+29&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(4,3)&-12/ \textless daf\textgreater (2nd parameter) \\
-fde+31&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(12)&44/ \textless caf\textgreater \\
+fde+29&\livelink{chap:DWCFAoffset}{DW\-\_CFA\-\_offset}(4,3)&-12/\textless daf\textgreater (2nd parameter) \\
+fde+31&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(12)&44/\textless caf\textgreater \\
 fde+32&\livelink{chap:DWCFArestore}{DW\-\_CFA\-\_restore}(4)& \\
 fde+33&\livelink{chap:DWCFAadvanceloc}{DW\-\_CFA\-\_advance\-\_loc}(1) & \\
 fde+34&\livelink{chap:DWCFArestore}{DW\-\_CFA\-\_restore}(6) & \\
@@ -1403,7 +1396,7 @@ are required in actual use.
 
 For conciseness, declaration coordinates and call coordinates are omitted.
 
-\subsection{Alternative 1: inline both OUTER and INNER}
+\subsection{Alternative \#1: inline both OUTER and INNER}
 \label{app:inlinebothouterandinner}
 
 A suitable abstract instance for an alternative where both
@@ -1530,7 +1523,7 @@ INNER.CI.1.3:
 \label{fig:inliningexample1concreteinstance}
 \end{figure}
 
-\subsection{Alternative 2: Inline OUTER, multiple INNERs}
+\subsection{Alternative \#2: Inline OUTER, multiple INNERs}
 \label{app:inlineoutermultiipleinners}
 
 
@@ -1551,7 +1544,7 @@ Figure \refersec{fig:inliningexample1abstractinstance}
 in that INNER lacks a 
 \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute
 and therefore is not a distinct abstract instance. INNER
-is merely an out\dash of\dash line routine that is part of OUTERs
+is merely an out\dash of\dash line routine that is part of OUTER\textquoteright s
 abstract instance. This is reflected in the Figure by
 \addtoindexx{abstract instance!example}
 the fact that the labels for INNER use the substring OUTER
@@ -1682,7 +1675,7 @@ OUTER.CI.2.6:
 \label{fig:inliningexample2concreteinstance}
 \end{figure}
 
-\subsection{Alternative 3: inline OUTER, one normal INNER}
+\subsection{Alternative \#3: inline OUTER, one normal INNER}
 \label{app:inlineouteronenormalinner}
 
 In the third approach, one normal subprogram for INNER is
@@ -1694,7 +1687,7 @@ Figure \refersec{fig:inliningexample3abstractinstance}.
 
 The most distinctive aspect of that Figure is that subprogram
 INNER exists only within the abstract instance of OUTER,
-and not in OUTERs concrete instance. In the abstract
+and not in OUTER\textquoteright s concrete instance. In the abstract
 \addtoindexx{concrete instance!example}
 \addtoindexx{abstract instance!example}
 instance of OUTER, the description of INNER has the full
@@ -1858,7 +1851,8 @@ float arr[square(9)]; // square() called and inlined
 \caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
 \end{figure}
 
-\begin{figure}[h]
+
+\begin{figure}[!h]
 \begin{dwflisting}
 \begin{alltt}
         ! For variable mass
@@ -1915,7 +1909,7 @@ Figure \refersec{fig:unicodecharacterexamplesource}
 can be described in DWARF as illustrated in 
 Figure \refersec{fig:unicodecharacterexampledwarfdescription}.
 
-\begin{figure}[h]
+\begin{figure}[!h]
 \begin{lstlisting}[numbers=none]
 // C++ source
 //
@@ -1999,6 +1993,7 @@ E e1;
 \end{figure}
 
 
+\clearpage
 \section{Template Examples}
 \label{app:templateexample}
 
@@ -2052,12 +2047,13 @@ with int in the instance. There exist situations where it is
 not possible for the DWARF to imply anything about the nature
 of the original template. 
 
+\needlines{10}
 Consider the C++ template source in
 Figure \refersec{fig:ctemplateexample2source}
 and the DWARF that can describe it in
 Figure \refersec{fig:ctemplateexample2dwarf}.
 
-\begin{figure}[h]
+\begin{figure}[!h]
 \begin{lstlisting}
 // C++ source
 //
@@ -2074,7 +2070,7 @@ Figure \refersec{fig:ctemplateexample2dwarf}.
     consume(obj);
 \end{lstlisting}
 \caption{C++ template example \#2: source}
-\label{ctemplateexample2source}
+\label{fig:ctemplateexample2source}
 \end{figure}
 
 \begin{figure}[h]
@@ -2252,4 +2248,4 @@ using Z = Y<int>;
 \end{dwflisting}
 \caption{C++ template alias example \#2: DWARF description}
 \label{fig:ctemplatealiasexample2dwarf}
-\end{figure}
\ No newline at end of file
+\end{figure}