Checkpoint following major upgrade of the Name index figure (Fig 6.1)
authorRon Brender <ron.brender@gmail.com>
Thu, 6 Aug 2015 21:56:47 +0000 (17:56 -0400)
committerRon Brender <ron.brender@gmail.com>
Thu, 6 Aug 2015 21:56:47 +0000 (17:56 -0400)
contributed by Cary Coutant.

Signed-off-by: Ron Brender <ron.brender@gmail.com>
dwarf5/latexdoc/changesummary.tex
dwarf5/latexdoc/datarepresentation.tex
dwarf5/latexdoc/dwarf5.tex
dwarf5/latexdoc/examples.tex
dwarf5/latexdoc/introduction.tex
dwarf5/latexdoc/otherdebugginginformation.tex
dwarf5/latexdoc/pgfcmdsfornameindexfig.tex [new file with mode: 0644]
dwarf5/latexdoc/splitobjects.tex

index 296aae5..c88412a 100644 (file)
@@ -15,9 +15,9 @@ This change summary is included only in draft versions of this document.
 \begin{longtable}{ll}
 \textbf{Date}  & \textbf{Issue Incorporated or Other Change}   \\ \hline       \\
 \endhead
-7/28-29/2015    & 150623.1 (MD5 digest), new F.3 (.dwp files), remove trial Selected Glossary, \\
-                & more editorial work X \\
-6/30-7/14/2015  & Revise 3.1 Compilation Units, replace Figure 6.1, \\
+7/28-8/6/2015   & 150623.1 (MD5 digest), new F.3 (.dwp files), remove trial Selected Glossary, \\
+                & replace Fig 6.1 (again), more editorial work X \\
+6/30-7/14/2015  & Revise 3.1 Compilation Units, replace Figure 6.1 (Name index), \\
                 & add trial Selected Glossary appendix, more editorial work IX \\
 6/24-29/2015    & More editorial work VIII \\
 6/24/2015       & 150608.1 (DW\_AT\_dwo\_id value is implementation-defined) \\
index f742764..95891e9 100644 (file)
@@ -206,7 +206,7 @@ of these offsets requires relocation. Depending on the implementation,
 these relocations may be implicit (that is, the producer may not need to
 emit any explicit relocation information for these offsets).
 
-\item The \HFNdebuginfooffset{} field in the \dotdebugaranges header and 
+\item The \HFNdebuginfooffset{} field in the \dotdebugaranges{} header and 
 the list of compilation units following the \dotdebugnames{} header contain 
 references to the \dotdebuginfo{} section.  These references require relocation 
 so that after linking they refer to the correct contribution in the combined 
@@ -273,11 +273,8 @@ section. The string offsets table is necessary only if
 the skeleton compilation unit uses the \DWFORMstrx{} form.
 \end{itemize}
 The attributes contained in the skeleton compilation
-unit can be used by a DWARF consumer to find the 
-
-split or hybrid 
-
-DWARF object file that contains the second partition.
+unit can be used by a DWARF consumer to find the split or 
+hybrid DWARF object file that contains the second partition.
 
 \subsubsection{Second Partition (Unlinked or In \texttt{.dwo} File)}
 The second partition contains the debugging information that
@@ -1193,6 +1190,7 @@ Table \referfol{tab:tagencodings}.
 \end{longtable}
 \end{centering}
 
+\needlines{8}
 Following the tag encoding is a 1-byte value that determines
 whether a debugging information entry using this abbreviation
 has child entries or not. If the value is 
@@ -2454,7 +2452,7 @@ Table \refersec{tab:basetypeencodingvalues}
 \end{longtable}
 \end{centering}
 
-\needlines{4}
+\vspace*{1cm}
 The encodings of the constants used in the 
 \DWATdecimalsign{} attribute 
 are given in 
@@ -2468,17 +2466,15 @@ Table \refersec{tab:decimalsignencodings}.
 \endfirsthead
   \bfseries Decimal sign code name&\bfseries Value\\ \hline
 \endhead
-  \hline \emph{Continued on next page}
-\endfoot
+%  \hline \emph{Continued on next page}
+%\endfoot
   \hline
 \endlastfoot
-
-\DWDSunsigned{} & 0x01  \\
-\DWDSleadingoverpunch{} & 0x02  \\
+\DWDSunsigned{}          & 0x01  \\
+\DWDSleadingoverpunch{}  & 0x02  \\
 \DWDStrailingoverpunch{} & 0x03  \\
-\DWDSleadingseparate{} & 0x04  \\
-\DWDStrailingseparate{} & 0x05  \\
-
+\DWDSleadingseparate{}   & 0x04  \\
+\DWDStrailingseparate{}  & 0x05 \\ 
 \end{longtable}
 \end{centering}
 
index 6b226d2..196c09e 100644 (file)
@@ -3,7 +3,7 @@
 % If draft is in the document class list, pix are just suggested
 % by an outline, the pic does not appear as a picture.
 %
-\newcommand{\docdate}{July 29, 2015}
+\newcommand{\docdate}{August 6, 2015}
 %
 \usepackage{ifthen}
 \newcommand{\ifthen}[2]{\ifthenelse{#1}{#2}{}}
 %\renewcommand{\familydefault}{phv}  % font family helvetica
 %
 
-\usepackage{url}          % For color in letters. Links instead?
-\usepackage[usenames]{color} % For color in letters. Links instead?
-\usepackage{ellipsis}     % Provides ... as \dots
+\usepackage{url}          % for color in letters. Links instead?
+\usepackage[usenames]{color}%for color in letters. Links instead?
+\usepackage{ellipsis}     % provides ... as \dots
+\usepackage[utf8]{inputenc}% to type directly diacritic characters
 %\usepackage{color}
 \usepackage{listings}
 \usepackage{alltt}
 \lstset{ %
 language={},               % choose the language of the code
-basicstyle=\footnotesize\ttfamily,  % the size of the fonts that are used for the code
+basicstyle=\footnotesize\ttfamily, % the size of the fonts that are used for the code
 numbers=none,              % where to put the line-numbers
 numberstyle=\footnotesize, % the size of the fonts that are used for the line-numbers
 numberfirstline=true,
@@ -51,7 +52,10 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \usepackage{float}
 \restylefloat{figure}
 \usepackage{amsmath}       % Provides \nobreakdash
+\usepackage{amssymb}       % maths
 \usepackage{graphicx}      % For pictures
+\usepackage{epstopdf}      % Autoconvert .eps to .pdf
+\epstopdfsetup{suffix=-generated} % Mark generaed PDF as such
 \usepackage{longtable}     % For multipage tables
 \usepackage{hhline}        % Single column horizontal lines
 \usepackage{varioref}      % defines \vref
@@ -63,12 +67,17 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \usepackage{changepage}    % For odd/even page checks
 \usepackage[usenames,dvipsnames]{xcolor}
 \usepackage{lscape}        % For landscape mode (Appendix B)
-\usepackage{tikz}         % graphics (Appendix B)
+\usepackage{tikz}         % graphics (Name Index (Fig 6.1), Appendix B)
+\usetikzlibrary{arrows}
+\usetikzlibrary{arrows.meta}
+\usetikzlibrary{backgrounds}
+\usetikzlibrary{calc}
+\usetikzlibrary{chains}
+\usetikzlibrary{decorations.pathreplacing}
 \usetikzlibrary{shapes.geometric}
 \usetikzlibrary{shapes.multipart}
-\usetikzlibrary{arrows,decorations.pathmorphing}
+\usetikzlibrary{shapes.symbols}
 \usepackage{changebar}     % For change bars in margin
-\usepackage{amssymb}       % For math symbols
 \usepackage{makeidx}       % For making an index
 % hyperref must be the last package listed.
 % The hyperref settings helps hypertext get links right in the 
@@ -87,9 +96,6 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
   }
   {\end{list}}
 
-% broken somehow.
-%\newcommand{\myindent1}[1]{\begin{myindentpara}{1cm}#1\end{myindentpara}}
-
 \hypersetup{colorlinks=true,
   %bookmarks=true,
   pdfauthor={\dwf\ Committee},
@@ -217,6 +223,10 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \newcommand{\definitionx}[1]{\definition{\addtoindex{#1}}}
 \include{dwarfnamecmds}
 
+% Define commands for pgf use in the name index figure (Fig 6.1)
+%
+\include{pgfcmdsfornameindexfig}
+
 %--- Begin the document pages
 %
 \begin{document}
@@ -330,8 +340,8 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \include{programscope}                  \emptypage
 \include{dataobject}                    %\emptypage
 \include{typeentries}                   %\emptypage
-\include{otherdebugginginformation}    %\emptypage
-\include{datarepresentation}            \emptypage
+\include{otherdebugginginformation}    \emptypage
+\include{datarepresentation}            %\emptypage
 
 %  The \appendix command toggles us into appendix chapters
 \appendix
@@ -341,7 +351,7 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \include{encodingdecoding}              \emptypage
 \include{examples}                      %\emptypage
 \include{compression}                   \emptypage
-\include{splitobjects}                 %\emptypage
+\include{splitobjects}                 \emptypage
 \include{sectionversionnumbers}         \emptypage
 \include{gnulicense}                    \emptypage
 
index e083a3d..fc5e72b 100644 (file)
@@ -2260,6 +2260,7 @@ fde+44 && \\
 \end{longtable}
 \end{centering}
 
+\needlines{6}
 \section{Inlining Examples}
 \label{app:inliningexamples}
 The pseudo\dash source in 
@@ -3691,7 +3692,7 @@ This is shown in Figure \refersec{fig:callsiteexample1dwarf}.
             \DWATcallvalue(\DWOPbregthree{} 16 \DWOPderef)
 \end{alltt}
 \end{dwflisting}
-\caption{Call Site Example \#1: DWARF Encoding}
+\caption{Call site example \#1: DWARF encoding}
 \label{fig:callsiteexample1dwarf}
 \end{figure}
 
@@ -3732,7 +3733,7 @@ This is shown in Figure \refersec{fig:callsiteexample1dwarf}.
 \end{dwflisting}
 \begin{center}
 \vspace{3mm}
-Figure~\ref{fig:callsiteexample1dwarf} Call Site Example \#1: DWARF Encoding \textit{(concluded)}
+Figure~\ref{fig:callsiteexample1dwarf} Call site example \#1: DWARF encoding \textit{(concluded)}
 \end{center}
 \end{figure}
 
@@ -3763,7 +3764,7 @@ subroutine fn5 (n)
     call fn4 (x)
 end subroutine fn5
 \end{lstlisting}
-\caption{Call Site Example \#2: Source}
+\caption{Call site example \#2: source}
 \label{fig:callsiteexample2source}
 \end{figure}
 
@@ -3793,7 +3794,7 @@ L10:
     return
     
 \end{lstlisting}
-\caption{Call Site Example \#2: Code}
+\caption{Call site example \#2: code}
 \label{fig:callsiteexample2code}
 \end{figure}
 
@@ -3839,7 +3840,7 @@ Figure \refersec{fig:callsiteexample2dwarf}.
         
 \end{alltt}
 \end{dwflisting}
-\caption{Call Site Example \#2: DWARF Encoding}
+\caption{Call site example \#2: DWARF encoding}
 \label{fig:callsiteexample2dwarf}
 \end{figure}
 
@@ -3873,7 +3874,7 @@ DWARF encoding of macro information (see Section \refersec{chap:macroinformation
 #define D 3
 #define FUNCTION_LIKE_MACRO(x) 4+x
 \end{lstlisting}
-\caption{Macro example: Source}
+\caption{Macro example: source}
 \label{ref:macroexamplesource}
 \end{figure}
 
@@ -3982,7 +3983,7 @@ or may preclude sharing across compilations.
         0                             ! End macro unit
 \end{alltt}
 \end{dwflisting}
-\caption{Macro Example: Simple DWARF Encoding}
+\caption{Macro example: simple DWARF encoding}
 \label{fig:macroexamplesimpledwarfencoding}
 \end{figure}
 
@@ -4038,6 +4039,6 @@ s$1:    String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
 s$2:    String: "LONGER\_MACRO 1"
 \end{alltt}
 \end{dwflisting}
-\caption{Macro Example: Sharable DWARF Encoding}
+\caption{Macro example: sharable DWARF encoding}
 \label{fig:macroexampledsharablewarfencoding}
 \end{figure}
\ No newline at end of file
index aebf862..de84adb 100644 (file)
@@ -88,8 +88,72 @@ format definition itself. The several appendices consist only
 of explanatory or supplementary material, and are not part
 of the formal definition.
 
-\section{Vendor Extensibility}
+\bb
+\section{Objectives and Rationale}
 
+DWARF has had a set of objectives since its inception which have guided the design and evolution of the debugging format.  A discussion of these objectives and the rationale behind them may help with an understanding of the DWARF Debugging Format. 
+
+Although DWARF Version 1 was developed in the late 1980's as a format to support debugging C programs written for AT\&T hardware running SVR4, DWARF Version 2 and later has evolved far beyond this origin. One difference between DWARF and other object formats is that the latter are often specific to a particular language, architecture, and/or operating system. 
+
+\subsection{Language Independence}
+DWARF is applicable to a broad range of existing procedural languages and is designed to be extensible to future languages.  These languages may be considered to be "C-like" but the characteristics of C are not incorporated into DWARF Version 2 and later, unlike DWARF Version 1 and other debugging formats.  DWARF abstracts concepts as much as possible so that the description can be used to describe a program in any language. As an example, the DWARF descriptions used to describe C functions, Pascal subroutines, and Fortran subprograms are all the same, with different attributes used to specify the differences between these similar programming language features. 
+
+On occasion, there is a feature which is specific to one particular language and which doesn't appear to have more general application.  For these, DWARF has a description designed to meet the language requirements, although, to the extent possible, an effort is made to generalize the attribute. An example of this is the \DWTAGconditionNAME{} DIE, which is used to describe \addtoindex{COBOL} level 88 conditions, which is described in abstract terms rather than COBOL-specific terms.  Conceivably, this TAG might be used with a different language which had similar functionality. 
+
+\subsection{Architecture Independence}
+DWARF can be used with a wide range of processor architectures, whether byte or word oriented, linear or segmented, with any word or byte size.  DWARF can be used with Von Neumann architectures, using a single address space for both code and data; Harvard architectures, with 
+separate code and data address spaces; and potentially for other architectures such as DSPs with their idiosyncratic memory organizations.  DWARF can be used with common register-oriented architectures or with stack architectures. 
+
+DWARF assumes that memory has individual units (words or bytes) which have unique addresses which are ordered.  (Some architectures like the i386 can represent the same physical machine location with different segment/offset pairs.  Identifying aliases is an implementation issue.)
+
+\subsection{Operating System Independence}
+DWARF is widely associated with SVR4 Unix and similar operating systems like BSD and Linux.  DWARF fits well with the section organization of the ELF object file format. Nonetheless, DWARF attempts to be independent of either the OS or the object file format.  There have been implementations of DWARF debugging data in OMF or COFF object files. 
+
+DWARF assumes that any object file format will be able to distinguish the various DWARF data sections in some fashion, preferably by name. 
+
+DWARF makes a few assumptions about functionality provided by the underlying operating system.  DWARF data sections can be read sequentially and independently, for example, to read the \dotdebugabbrev{} section before the \dotdebuginfo{} section.  Each DWARF data section is a sequential sequence of 8-bit bytes, numbered starting with zero.  The presence of offsets from one DWARF data section into other data sections does not imply that the underlying OS must be able to position files randomly; a data section could be read sequentially and indexed using the offset. 
+
+\subsection{Compact Data Representation} 
+The DWARF description is designed to be a compact file-oriented representation. In most cases, it is anticipated that DWARF debug data will be read by a consumer (usually a debugger) and converted into a more efficiently accessed internal representation.  For the most part, the DWARF data in a section is not the same as this internal representation. 
+
+There are several encodings which achieve this goal, such as the TAG and attribute abbreviations or the line number encoding.  References from one section to another, especially to refer to strings, allow these sections to be compacted to eliminate duplicate data. 
+
+There are multiple schemes for eliminating duplicate data or reducing the size of the DWARF debug data associated with a given file.  These include COMDAT, used to eliminate duplicate function or data definitions, the split DWARF object files which allow a consumer to find DWARF data in files other than the executable, or the type units, which allow similar type definitions from multiple compilations to be combined. 
+
+There is a tension between this objective and the following objective. Every compaction scheme results in more processing which needs to be performed to process the DWARF debug data. 
+
+\subsection{Efficient Processing} 
+DWARF is designed to be processed efficiently, so that a producer (a compiler) can generate the debug descriptions incrementally and a consumer can read only the descriptions which it needs at a given time. The data formats are designed to be efficiently interpreted by a consumer.
+
+As mentioned, there is a tension between this objective and the preceding one.  A DWARF data representation which resembles an internal data representation may lead to faster processing, but at the expense of larger data files. This may also constrain the possible implementations.
+
+\subsection{Implementation Independence}
+DWARF attempts to allow developers the greatest flexibility in designing implementations, without mandating any particular design decisions.  We avoid issues which can be described as “Quality of Implementation”, where the decisions made by an implementer may affect performance or functionality.  
+
+\subsection{Explicit rather than Implicit Description}
+DWARF describes the source to object translation explicitly rather than using common practice or convention as an implicit understanding between producer and consumer.  For example, where other debugging formats assume that a debugger knows how to unwind the stack, moving from one stack frame to the next using implicit knowledge about the architecture or operating system, DWARF makes this explicit in the Call Frame Information description.
+
+\subsection{Avoid Duplication of Information}
+DWARF has a goal of describing characteristics of a program once, rather than repeating the same information multiple times.  The string sections can be compacted to eliminate duplicate strings, for example.  Other compaction schemes or references between sections support this.
+Whether a particular implementation is effective at eliminating duplicate data, or even attempts to, is a Quality of Implementation issue.  
+
+\subsection{Leverage Other Standards}
+Where another standard exists which describes how to interpret aspects of a program, DWARF defers to that standard rather than attempting to duplicate the description.  For example, C++ has specific rules for deciding which function to call depending name, scope, argument types, and other factors.  DWARF describes the functions and arguments, but doesn't attempt to describe how one would be selected by a consumer performing any particular operation.
+
+\subsection{Limited Dependence on Tools}
+DWARF data is designed so that it can be processed by commonly available assemblers, linkers, and other support programs, without requiring additional functionality specifically to support DWARF data.  This may require the implementer to be careful that they do not generate DWARF data which cannot be processed by these programs.  
+Conversely, an assembler which can generate LEB128 values may allow the compiler to generate more compact descriptions, and a linker which understands the format of string sections can merge these sections.  Whether or not an implementation includes these functions is a Quality of Implementation issue, not mandated by the DWARF specification.
+
+\subsection{Separate Description from Implementation}
+DWARF intends to describe the translation of a program from source to object, while neither mandating any particular design nor making any other design difficult.  For example, DWARF describes how the arguments and local variables in a function are to be described, but doesn't specify how this data is collected or organized by a producer.  
+Where a particular DWARF feature anticipates that it will be implemented in a certain fashion, non-normative text will suggest but not require this design.
+
+\subsection{Permissive rather than Prescriptive}
+The DWARF Standard specifies the meaning of DWARF descriptions.  It does not specify what a particular producer should generate for any source to object conversion, nor what a particular consumer should do with this description.  DWARF is permissive, allowing different producer to generate different descriptions for the same source to object conversion.  As long as the DWARF description follows this specification, the producer is generating valid DWARF.
+For example, DWARF allows producers to identify the end of a function prologue in the Line Information so that a debugger can stop at this location.  A producer which does this is generating valid DWARF, as is another which doesn't.  
+
+\subsection{Vendor Extensibility}
+\eb
 This document does not attempt to cover all interesting
 languages or even to cover all of the possible debugging
 information needs for its primary target languages. 
@@ -109,9 +173,9 @@ All
 names and values not reserved for vendor additions, however,
 are reserved for future versions of this document.
 
-DWARF is intended to be permissive rather than
-prescriptive. 
+\bb
 Where this specification provides a means for
+\eb
 describing the source language, implementors are expected
 to adhere to that specification. 
 For language features that
@@ -149,6 +213,7 @@ extensions. It also adds a string section specific to the line number table
 (\dotdebuglinestr)
 to properly support the common practice of stripping all DWARF sections
 except for line number information.
+\needlines{4}
 \item Add a split object file and package representations to allow most 
 DWARF information to be compacted and/or kept separate from an executable 
 or shared image. This includes new sections 
index 40eac16..39b5cd1 100644 (file)
@@ -45,6 +45,7 @@ by name. As with the definition of global data objects, this
 would require a search of all the top level type definitions
 of all compilation units in a program.}
 
+\needlines{4}
 \textit{To find the debugging information associated with a subroutine,
 given an address, a debugger can use the low and high PC
 attributes of the compilation unit entries to quickly narrow
@@ -182,170 +183,326 @@ Figure \referfol{fig:nameindexlayout}.
 \end{enumerate}
 
 \begin{figure}[p]
-
+\bb
+\figurepart{1}{2}
 \begin{center}
-\newcommand{\thisblue}{blue!10}
-\newcommand{\thisyellow}{yellow!20}
-\newcommand{\invispblu}{\textcolor{\thisblue}{p}}
-\newcommand{\invispyel}{\textcolor{\thisyellow}{p}}
-  \begin{tikzpicture}[every node/.style={draw, anchor=text,
-        node distance=2.5cm,
-        text width=3.5cm, font=\normalsize},
-        description/.style={
-          draw=none,
-          font=\em\small,
-          node distance=5cm,
-          text width=5cm
-        },
-        table/.style={
-          font=\small,
-          draw=black,
-          rectangle split,
-          fill=\thisyellow
-        },
-        caption/.style={
-          anchor=south,
-          font=\small,
-          draw=none
-        }]
-    \node (header) [font=\small,
-                    fill=\thisblue,
-                    rectangle split,
-                    rectangle split allocate boxes=8,
-                    rectangle split parts=8] at (0, -1.3)
-          {Header\invispblu
-            \nodepart{two}
-            CU list\invispblu
-            \nodepart{three}
-            Local TU list\invispblu
-            \nodepart{four}
-            Foreign TU list\invispblu
-            \nodepart{five}
-            Hash table\invispblu
-            \nodepart{six}
-            Name table\invispblu
-            \nodepart{seven}
-            Abbrev table\invispblu
-            \nodepart{eight}
-            Entry pool\invispblu
-          };
-    \draw node [caption] at (header.north) {Name Index} ;
-
-    \node (cuofs) [table,
-                   rectangle split allocate boxes=4,
-                   rectangle split parts=4]  at (7.5,0)
-         {CU 0 offset\invispyel
-          \nodepart{two}
-          CU 1 offset\invispyel
-          \nodepart{three}
-          CU 2 offset\invispyel
-          \nodepart{four}
-          \dots
-         };
-        \node (cusecofs) [description,right of=cuofs] {section offset \\ of CU header} ;
-    \node (tuofs) [below of=cuofs,
-                   table,
-                   rectangle split allocate boxes=4,
-                   rectangle split parts=4]
-         {TU 0 offset\invispyel
-          \nodepart{two}
-          TU 1 offset\invispyel
-          \nodepart{three}
-          TU 2 offset\invispyel
-          \nodepart{four}
-          \dots
-         };
-    \node (tusecofs) [description,right of=tuofs] {section offset \\ of TU header} ;
-    \node (tusigs) [below of=tuofs, 
-                    table,
-                    rectangle split allocate boxes=4,
-                    rectangle split parts=4]
-         {TU $n$ sig.\invispyel
-          \nodepart{two}
-          TU $n+1$ sig.\invispyel
-          \nodepart{three}
-          TU $n+2$ sig.\invispyel
-          \nodepart{four}
-          \dots
-         };
-   \node (typesigs) [description,right of=tusigs] {type signature \\ of foreign TU} ;
-
-   \matrix (hashtable) [draw,style=dashed,column sep=8mm] at (0, -10)
-           {\node (buckets) [style=solid, table, text width=3cm,
-                             rectangle split allocate boxes=4,
-                             rectangle split parts=4]
-                  {index to hashes\invispyel
-                  \nodepart{two}\invispyel
-                  \nodepart{three}\invispyel
-                  \nodepart{four}\dots
-                  } ;
-            \draw node [caption] at (buckets.north) {~Buckets} ;
-            &
-            \node (hashes) [style=solid, table, text width=3cm,
-                            rectangle split allocate boxes=6,
-                            rectangle split parts=6]
-                  {hash value\invispyel
-                  \nodepart{two}\invispyel
-                  \nodepart{three}\invispyel
-                  \nodepart{four}\invispyel
-                  \nodepart{five}\invispyel
-                  \nodepart{six}\invispyel
-                  } ;
-            \draw node [caption] at (hashes.north) {~Hashes} ;
-            \\
-           };
-    \node (names) [right of=hashes, node distance=5cm,
-                   style=solid,
-                   table,
-                   rectangle split allocate boxes=6,
-                   rectangle split parts=6]
-          {strp \hspace{1cm} entry
-           \nodepart{two}\invispyel
-           \nodepart{three}\invispyel
-           \nodepart{four}\invispyel
-           \nodepart{five}\invispyel
-           \nodepart{six}\invispyel
-          };
-    \draw node [caption] at (names.north) {Names} ;
-    \path (names.north) edge (names.south) ;
-
-    \draw[thick, double distance=3pt, implies-space] (header.two east)   -- (cuofs.west) ;
-    \draw[thick, double distance=3pt, implies-space] (header.three east) -- (tuofs.west) ;
-    \draw[thick, double distance=3pt, implies-space] (header.four east)  -- (tusigs.west) ;
-
-    \path[-triangle 45]
-        (cuofs)              edge (cusecofs)
-        (tuofs)              edge (tusecofs)
-        (tusigs)             edge (typesigs)
-        (buckets.one east)   edge (hashes.one west)
-        (buckets.two east)   edge (hashes.three west)
-        (buckets.three east) edge (hashes.six west)
-        ;
-    \path[loosely dashed, thin, open triangle 45-open triangle 45]
-        (hashes.one east)    edge (names.one west)
-        (hashes.two east)    edge (names.two west)
-        (hashes.three east)  edge (names.three west)
-        (hashes.four east)   edge (names.four west)
-        (hashes.five east)   edge (names.five west)
-        (hashes.six east)    edge (names.six west)
-        ;
-    \draw[thick, double distance=3pt, implies-space] (header.five east) 
-        .. controls +(south east:2cm) .. (hashtable.north) ;
-    \draw[thick, double distance=3pt, implies-space] (header.six east)
-        .. controls (hashes.north) and (tusigs.south east) .. (names.north) ;
-    
-    \node [text width=9cm, draw=none] at (0,-15.5) {\textit{Notes:}} ;   
-    \draw [thick, double distance=3pt, implies- ] (0,-16) -- (1.3,-16)
-          node[right=2mm, text width=9cm, draw=none, node distance=1cm] 
-          {\textit{indicates an expanded view of the indicated part}} ;
-    \draw [loosely dashed, thin, open triangle 45-open triangle 45] (0,-16.5) -- (1.3,-16.5) 
-          node[right=2mm, text width=9cm, draw=none] {\textit{indicates correspondence}} ;
-          
-  \end{tikzpicture}
-\end{center}
+%\includegraphics[keepaspectratio=true,scale=1.0]{name-index-drawings-6p1}
+
+\begin{tikzpicture}[
+  every node/.style={node font=\small, anchor=north west, text height=.8em, text depth=.2em, inner sep=4pt, outer ysep=0},
+  caption/.style={node font=\small \bfseries, text width=90pt},
+  overview/.style={draw, node font=\small, minimum height=28pt, text width=80pt},
+  detail1/.style={draw, minimum height=14pt, text width=116pt},
+  detail2/.style={draw, minimum height=28pt, text width=116pt},
+  detail3/.style={draw, minimum height=48pt, text width=116pt},
+  detail4/.style={draw, minimum height=72pt, text width=116pt},
+  ellip/.style={draw, shape=broken rectangle, minimum height=14pt, text width=116pt},
+  explode/.style={draw=black!50, fill=black!20, line join=bevel},
+  header/.style={fill=headerblue},
+  culist/.style={fill=cutuyellow},
+  buckets/.style={fill=bucketsblue},
+  hashes/.style={fill=hashesgreen},
+  stroffsets/.style={fill=stroffsetspink},
+  entryoffsets/.style={fill=entryoffsetspink},
+  indexentries/.style={fill=indexentriesorange}
+]
+
+% Name Table Overview
+
+\begin{scope}[start chain=going below, node distance=0]
+  \node           [on chain,caption]  {Name Index};
+  \node (header)  [on chain,overview,header] {Header};
+  \node (culist)  [on chain,overview,header] {CU List};
+  \node (ltulist) [on chain,overview,header] {Local TU List};
+  \node (ftulist) [on chain,overview,header] {Foreign TU List};
+  \node (hash)    [on chain,overview,header] {Hash Table};
+  \node (names)   [on chain,overview,header] {Name Table};
+  \node (abbrev)  [on chain,overview,header] {Abbrev Table};
+  \node (pool)    [on chain,overview,header] {Entry Pool};
+\end{scope}
+
+% Exploded View of CU List
+
+\begin{scope}[start chain=going below, node distance=0, shift={($(header.north east) + (72pt,18pt)$)}]
+  \node (cu0) [on chain,detail1,culist] {offset to CU 0};
+  \node (cu1) [on chain,detail1,culist] {offset to CU 1};
+  \node (cu2) [on chain,ellip,culist]   {\dots};
+  \node (cu3) [on chain,detail1,culist] {offset to CU $k - 1$};
+\end{scope}
+
+\begin{scope}[on background layer]
+  \filldraw [explode] (culist.north east) -- (cu0.north west) -- (cu3.south west) -- (culist.south east) -- cycle;
+\end{scope}
+
+\path [decoration={brace,amplitude=6pt}] ([xshift=9pt]cu0.north east)
+      [draw,decorate] -- ([xshift=9pt]cu3.south east)
+      node [midway,right,inner xsep=9pt] {\texttt{comp\_unit\_count} $(= k)$};
+
+% Exploded View of Local TU List
+
+\begin{scope}[start chain=going below, node distance=0, shift={($(cu3.south west) + (0,-9pt)$)}]
+  \node (ltu0) [on chain,detail1,culist] {offset to TU 0};
+  \node (ltu1) [on chain,detail1,culist] {offset to TU 1};
+  \node (ltu2) [on chain,ellip,culist]   {\dots};
+  \node (ltu3) [on chain,detail1,culist] {offset to TU $t - 1$};
+\end{scope}
+
+\begin{scope}[on background layer]
+  \filldraw [explode] (ltulist.north east) -- (ltu0.north west) -- (ltu3.south west) -- (ltulist.south east) -- cycle;
+\end{scope}
+
+\path [decoration={brace,amplitude=6pt}] ([xshift=9pt]ltu0.north east)
+      [draw,decorate] -- ([xshift=9pt]ltu3.south east)
+      node [midway,right,inner xsep=9pt] {\texttt{local\_type\_unit\_count} $(= t)$};
+
+% Exploded View of Foreign TU List
+
+\begin{scope}[start chain=going below, node distance=0, shift={($(ltu3.south west) + (0,-9pt)$)}]
+  \node (ftu0) [on chain,detail1,culist] {signature of TU $t$};
+  \node (ftu1) [on chain,detail1,culist] {signature of TU $t + 1$};
+  \node (ftu2) [on chain,ellip,culist]   {\dots};
+  \node (ftu3) [on chain,detail1,culist] {signature of TU $t + f - 1$};
+\end{scope}
+
+\begin{scope}[on background layer]
+  \filldraw [explode] (ftulist.north east) -- (ftu0.north west) -- (ftu3.south west) -- (ftulist.south east) -- cycle;
+\end{scope}
+
+\path [decoration={brace,amplitude=6pt}] ([xshift=9pt]ftu0.north east)
+      [draw,decorate] -- ([xshift=9pt]ftu3.south east)
+      node [midway,right,inner xsep=9pt] {\texttt{foreign\_type\_unit\_count} $(= f)$};
+
+% Exploded View of Hash Table
+
+\begin{scope}[start chain=going below, node distance=0, shift={($(ftu3.south west) + (0,-9pt)$)}]
+  \node (hash0) [on chain,detail2,buckets] {Buckets};
+  \node (hash1) [on chain,detail3,hashes]  {Hashes};
+\end{scope}
+
+\begin{scope}[on background layer]
+  \filldraw [explode] (hash.north east) -- (hash0.north west) -- (hash1.south west) -- (hash.south east) -- cycle;
+\end{scope}
+
+% Exploded View of Name Table
+
+\begin{scope}[start chain=going below, node distance=0, shift={($(hash1.south west) + (0,-9pt)$)}]
+  \node (name0) [on chain,detail3,stroffsets]   {String Offsets};
+  \node (name1) [on chain,detail3,entryoffsets] {Entry Offsets};
+\end{scope}
+
+\begin{scope}[on background layer]
+  \filldraw [explode] (names.north east) -- (name0.north west) -- (name1.south west) -- (names.south east) -- cycle;
+\end{scope}
+
+% Exploded View of Entry Pool
+
+\begin{scope}[shift={($(name1.south west) + (0,-9pt)$)}]
+  \node (pool0) [detail4,indexentries] {Index Entries};
+\end{scope}
+
+\begin{scope}[on background layer]
+  \filldraw [explode] (pool.north east) -- (pool0.north west) -- (pool0.south west) -- (pool.south east) -- cycle;
+\end{scope}
+
+%
+\path [decoration={brace,amplitude=6pt}] ([xshift=9pt]hash0.north east)
+      [draw,decorate] -- ([xshift=9pt]pool0.south east)
+      node [midway,right,inner xsep=9pt] {\textit{see figure part 2 on next page}};
+
+% Arrows pointing to .debug_info
+
+\begin{scope}[shift={($(cu0.north east) + (15pt,27pt)$)}]
+  \node (debuginfo) {\textit{.debug\_info}};
+\end{scope}
+
+\path ([xshift=28pt]cu0.center) coordinate (p1);
+\path ([xshift=14pt]p1) coordinate (c1);
+\path ([yshift=2pt]debuginfo.west) coordinate (p2);
+\path ([xshift=-14pt]p2) coordinate (c2);
+\draw [dashed,{Circle[open]}-{Stealth[]}] (p1) .. controls (c1) and (c2) .. (p2);
+
+\path ([xshift=28pt]ltu0.center) coordinate (p3);
+\path ([xshift=60pt]p3) coordinate (c3);
+\path ([yshift=-2pt]debuginfo.west) coordinate (p4);
+\path ([shift={(-21pt,-7pt)}]p4) coordinate (c4);
+\draw [dashed,{Circle[open]}-{Stealth[]}] (p3) .. controls (c3) and (c4) .. (p4);
+
+\end{tikzpicture}
+
 \caption{Name Index Layout}
-\label{fig:nameindexlayout}
+\label{fig:nameindexlayoutpart1}
+\end{center}
+\eb
+\end{figure}
 
+\begin{figure}[p]
+\bb
+\figurepart{2}{2}
+\begin{center}
+%\includegraphics[keepaspectratio=true,scale=1.0]{name-index-drawings-6p2}
+
+\begin{tikzpicture}[
+  every node/.style={node font=\small, anchor=north west, text height=.8em, text depth=.2em, inner sep=4pt, outer ysep=0},
+  % This diagram has a couple of two-line captions, so set the text depth
+  % to make room for the second line.
+  caption1/.style={node font=\small \bfseries, text depth=1.2em, text width=90pt},
+  caption2/.style={node font=\small \bfseries, text depth=1.2em, text width=41pt},
+  detail1/.style={draw, minimum height=14pt, text width=90pt},
+  detail2/.style={draw, minimum height=14pt, text width=41pt},
+  ellip1/.style={draw, shape=broken rectangle, minimum height=14pt, text width=90pt},
+  ellip2/.style={draw, shape=broken rectangle, minimum height=14pt, text width=41pt},
+  buckets/.style={fill=bucketsblue},
+  hashes/.style={fill=hashesgreen},
+  stroffsets/.style={fill=stroffsetspink},
+  entryoffsets/.style={fill=entryoffsetspink}
+]
+
+% Buckets
+
+\begin{scope}[start chain=going below, node distance=0]
+  \node           [on chain,caption1]        {\\ Buckets};
+  \node (bucket0) [on chain,detail1,buckets] {bucket 0};
+  \node (bucket1) [on chain,detail1,buckets] {bucket 1};
+  \node (bucket2) [on chain,ellip1,buckets]  {\dots};
+  \node (bucket3) [on chain,detail1,buckets] {bucket $b - 1$};
+\end{scope}
+
+\path [decoration={brace,amplitude=6pt}] ([xshift=36pt]bucket0.north east)
+      [draw,decorate] -- ([xshift=36pt]bucket3.south east)
+      node [midway,right,inner xsep=9pt] {\texttt{bucket\_count} $(= b)$};
+
+% Hashes
+
+\begin{scope}[start chain=going below, node distance=0, shift={($(bucket3.south east) + (18pt,-24pt)$)}]
+  \node (hashes) [on chain,caption1]       {\\ Hashes};
+  \node (hash0)  [on chain,detail1,hashes] {hash value 0};
+  \node (hash1)  [on chain,detail1,hashes] {hash value 1};
+  \node (hash2)  [on chain,detail1,hashes] {hash value 2};
+  \node (hash3)  [on chain,detail1,hashes] {hash value 3};
+  \node (hash4)  [on chain,detail1,hashes] {hash value 4};
+  \node (hash5)  [on chain,ellip1,hashes]  {\dots};
+  \node (hash6)  [on chain,detail1,hashes] {hash value $n - 1$};
+\end{scope}
+
+% String Offsets
+
+\begin{scope}[start chain=going below, node distance=0, shift={($(hashes.north east)$)}]
+  \node (strs) [on chain,caption2]           {String \\ Offsets};
+  \node (str0) [on chain,detail2,stroffsets] {};
+  \node (str1) [on chain,detail2,stroffsets] {};
+  \node (str2) [on chain,detail2,stroffsets] {};
+  \node (str3) [on chain,detail2,stroffsets] {};
+  \node (str4) [on chain,detail2,stroffsets] {};
+  \node (str5) [on chain,ellip2,stroffsets]  {};
+  \node (str6) [on chain,detail2,stroffsets] {};
+\end{scope}
+
+% Entry Offsets
+
+\begin{scope}[start chain=going below, node distance=0, shift={($(strs.north east)$)}]
+  \node (entries) [on chain,caption2]             {Entry \\ Offsets};
+  \node (entry0)  [on chain,detail2,entryoffsets] {};
+  \node (entry1)  [on chain,detail2,entryoffsets] {};
+  \node (entry2)  [on chain,detail2,entryoffsets] {};
+  \node (entry3)  [on chain,detail2,entryoffsets] {};
+  \node (entry4)  [on chain,detail2,entryoffsets] {};
+  \node (entry5)  [on chain,ellip2,entryoffsets]  {};
+  \node (entry6)  [on chain,detail2,entryoffsets] {};
+\end{scope}
+
+\path [decoration={brace,amplitude=6pt}] ([xshift=9pt]entry0.north east)
+      [draw,decorate] -- ([xshift=9pt]entry6.south east)
+      node [midway,right,inner xsep=9pt] {\texttt{name\_count} $(= n)$};
+
+% Arrows pointing to .debug_str and entry pool
+
+\path (str0.center) coordinate (p1);
+\path ([xshift=18pt]p1) coordinate (c1);
+\path ([shift={(36pt,45pt)}]p1) coordinate (p2);
+\path ([xshift=-18pt]p2) coordinate (c2);
+\draw [dashed,{Circle[open]}-{Stealth[]}] (p1) .. controls (c1) and (c2) .. (p2) node [anchor=west] {$.debug\_str$};
+
+\path (entry0.center) coordinate (p3);
+\path ([xshift=18pt]p3) coordinate (c3);
+\path ([shift={(36pt,27pt)}]p3) coordinate (p4);
+\path ([xshift=-18pt]p4) coordinate (c4);
+\draw [dashed,{Circle[open]}-{Stealth[]}] (p3) .. controls (c3) and (c4) .. (p4) node [anchor=west] {$entry\ pool$};
+
+% Arrows from buckets to hashes
+
+\path ([xshift=24pt]bucket0.center) coordinate (p5);
+\path ([xshift=144pt]p5) coordinate (c5);
+\path ([xshift=-108pt]hash0.west) coordinate (c6);
+\draw [dashed,{Circle[open]}-{Stealth[]}] (p5) .. controls (c5) and (c6) .. (hash0.west);
+
+\path ([xshift=24pt]bucket1.center) coordinate (p7);
+\path ([xshift=162pt]p7) coordinate (c7);
+\path ([xshift=-144pt]hash3.west) coordinate (c8);
+\draw [dashed,{Circle[open]}-{Stealth[]}] (p7) .. controls (c7) and (c8) .. (hash3.west);
+
+\end{tikzpicture}
+
+\vspace{15mm}
+
+%\includegraphics[keepaspectratio=true,scale=1.0]{name-index-drawings-6p3}
+\begin{tikzpicture}[
+  every node/.style={node font=\small, anchor=north west, text height=.8em, text depth=.2em, inner sep=4pt, outer ysep=0},
+  caption/.style={node font=\small \bfseries, text width=120pt},
+  detail/.style={draw, node font=\small, minimum height=14pt, text width=120pt},
+  ellip/.style={draw, shape=broken rectangle, minimum height=14pt, text width=120pt},
+  explode/.style={draw=black!50, fill=black!20, line join=bevel},
+  indexentries/.style={fill=indexentriesorange}
+]
+
+% Entry Pool
+
+\begin{scope}[start chain=going below, node distance=0]
+  \node           [on chain,caption]             {Entry Pool};
+  \node (entry0)  [on chain,detail,indexentries] {index entry \#1 for ``a''};
+  \node (entry1)  [on chain,detail,indexentries] {index entry \#2 for ``a''};
+  \node (entry2)  [on chain,ellip,indexentries]  {\dots};
+  \node (entry3)  [on chain,detail,indexentries] {0 \textit{(end of entries for ``a'')}};
+  \node (entry4)  [on chain,detail,indexentries] {index entry \#1 for ``b''};
+  \node (entry5)  [on chain,detail,indexentries] {index entry \#2 for ``b''};
+  \node (entry6)  [on chain,ellip,indexentries]  {\dots};
+  \node (entry7)  [on chain,detail,indexentries] {0};
+  \node (entry8)  [on chain,detail,indexentries] {index entry \#1 for ``c''};
+  \node (entry9)  [on chain,ellip,indexentries]  {\dots};
+\end{scope}
+
+% Exploded Index Entry
+
+\begin{scope}[start chain=going below, node distance=0, shift={($(entry1.north east) + (60pt,30pt)$)}]
+  \node (abbrev) [on chain,detail,indexentries] {abbrev code};
+  \node (attr1)  [on chain,detail,indexentries] {attribute};
+  \node (attr2)  [on chain,detail,indexentries] {attribute};
+  \node (attr3)  [on chain,ellip,indexentries]  {\dots};
+  \node (attr4)  [on chain,detail,indexentries] {attribute};
+\end{scope}
+
+\begin{scope}[on background layer]
+  \filldraw [explode] (entry1.north east) -- (abbrev.north west) -- (attr4.south west) -- (entry1.south east) -- cycle;
+\end{scope}
+
+% Arrows
+
+\node (from1) [anchor=east] at ([xshift=-36pt]entry0.west) {\textit{(from name table)}};
+\draw [dashed,-{Stealth[]}] (from1) -- (entry0.west);
+
+\node (from2) [anchor=east] at ([xshift=-36pt]entry4.west) {\textit{(from name table)}};
+\draw [dashed,-{Stealth[]}] (from2) -- (entry4.west);
+
+\node (from2) [anchor=east] at ([xshift=-36pt]entry7.west) {\textit{(from name table)}};
+\draw [dashed,-{Stealth[]}] (from2) -- (entry7.west);
+
+\end{tikzpicture}
+
+\vspace{3mm}
+%\caption{Name Index Layout \textit{(concluded)}}
+Figure~\ref{fig:nameindexlayoutpart1}: Name Index Layout \textit{(concluded)}
+%\label{fig:nameindexlayoutpart2}
+\end{center}
+\eb
 \end{figure}
 
 The formats of the header and the hash lookup table are described
@@ -373,6 +530,7 @@ the index, and two columns. The first column contains a reference to
 the name, as a string. The second column contains the offset within
 the entry pool of the list of index entries for the name.
 
+\needlines{4}
 The abbreviations table describes the formats of the entries in the
 entry pool. Like the DWARF abbreviations table in the \dotdebugabbrev{}
 section, it defines one or more abbreviation codes. Each abbreviation
@@ -542,6 +700,7 @@ four bytes in length.
 
 \end{enumerate}
 
+\needlines{4}
 \subsubsubsection{List of CUs}
 The list of CUs immediately follows the header. Each entry in the 
 list is an offset into the \dotdebuginfo{} section of the corresponding 
@@ -593,6 +752,7 @@ Each bucket contains the index of an entry in the hashes array. The
 hashes array is indexed starting at 1, and an empty bucket is
 represented by the value 0.
 
+\needlines{4}
 The hashes array contains a 
 \bb
 sequence
diff --git a/dwarf5/latexdoc/pgfcmdsfornameindexfig.tex b/dwarf5/latexdoc/pgfcmdsfornameindexfig.tex
new file mode 100644 (file)
index 0000000..a4c937a
--- /dev/null
@@ -0,0 +1,57 @@
+\definecolor {headerblue} {rgb}{.75,.75,.9}
+\definecolor {cutuyellow} {rgb}{1,1,.75}
+\definecolor {bucketsblue} {rgb}{.75,.875,1}
+\definecolor {hashesgreen} {rgb}{.8,1,.8}
+\definecolor {stroffsetspink} {rgb}{1,.8,.75}
+\definecolor {entryoffsetspink} {rgb}{1,.75,.8}
+\definecolor {indexentriesorange} {rgb}{1,.6,.6}
+
+% Define a "broken rectangle" shape to represent an ellipsis
+% in the drawing. The rectangle will have broken side borders
+% with hash marks to indicate that portions have been omitted.
+% FIXME: For more general use, the size and colors of the hash
+% marks should be parameterized with pgf keys.
+\makeatletter
+\pgfdeclareshape{broken rectangle}{
+  \inheritsavedanchors[from=rectangle]
+  \inheritanchorborder[from=rectangle]
+  \inheritanchor[from=rectangle]{center}
+  \inheritanchor[from=rectangle]{north}
+  \inheritanchor[from=rectangle]{south}
+  \inheritanchor[from=rectangle]{west}
+  \inheritanchor[from=rectangle]{east}
+  \inheritanchor[from=rectangle]{north west}
+  \inheritanchor[from=rectangle]{north east}
+  \inheritanchor[from=rectangle]{south west}
+  \inheritanchor[from=rectangle]{south east}
+  \inheritbackgroundpath[from=rectangle]
+  \beforebackgroundpath{
+    \pgfusepath{discard}
+    % Draw the two oblique rectangles and fill with white.
+    \pgfpathmoveto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.4}{\southwest}{\southwest\pgf@xa=\pgf@x\northeast\pgf@x=\pgf@xa}}{\pgfpointpolar{10}{-3pt}}}}
+    \pgfpathlineto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.4}{\southwest}{\southwest\pgf@xa=\pgf@x\northeast\pgf@x=\pgf@xa}}{\pgfpointpolar{10}{3pt}}}}
+    \pgfpathlineto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.6}{\southwest}{\southwest\pgf@xa=\pgf@x\northeast\pgf@x=\pgf@xa}}{\pgfpointpolar{10}{3pt}}}}
+    \pgfpathlineto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.6}{\southwest}{\southwest\pgf@xa=\pgf@x\northeast\pgf@x=\pgf@xa}}{\pgfpointpolar{10}{-3pt}}}}
+    \pgfclosepath
+    \pgfpathmoveto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.4}{\northeast\pgf@xa=\pgf@x\southwest\pgf@x=\pgf@xa}{\northeast}}{\pgfpointpolar{10}{-3pt}}}}
+    \pgfpathlineto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.4}{\northeast\pgf@xa=\pgf@x\southwest\pgf@x=\pgf@xa}{\northeast}}{\pgfpointpolar{10}{3pt}}}}
+    \pgfpathlineto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.6}{\northeast\pgf@xa=\pgf@x\southwest\pgf@x=\pgf@xa}{\northeast}}{\pgfpointpolar{10}{3pt}}}}
+    \pgfpathlineto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.6}{\northeast\pgf@xa=\pgf@x\southwest\pgf@x=\pgf@xa}{\northeast}}{\pgfpointpolar{10}{-3pt}}}}
+    \pgfclosepath
+    \pgfsetfillcolor{white}
+    \pgfusepath{fill}
+    % Now redraw the paths and stroke just the top and bottom edges of each rectangle.
+    \pgfpathmoveto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.4}{\southwest}{\southwest\pgf@xa=\pgf@x\northeast\pgf@x=\pgf@xa}}{\pgfpointpolar{10}{-3pt}}}}
+    \pgfpathlineto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.4}{\southwest}{\southwest\pgf@xa=\pgf@x\northeast\pgf@x=\pgf@xa}}{\pgfpointpolar{10}{3pt}}}}
+    \pgfpathmoveto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.6}{\southwest}{\southwest\pgf@xa=\pgf@x\northeast\pgf@x=\pgf@xa}}{\pgfpointpolar{10}{-3pt}}}}
+    \pgfpathlineto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.6}{\southwest}{\southwest\pgf@xa=\pgf@x\northeast\pgf@x=\pgf@xa}}{\pgfpointpolar{10}{3pt}}}}
+    \pgfpathmoveto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.4}{\northeast\pgf@xa=\pgf@x\southwest\pgf@x=\pgf@xa}{\northeast}}{\pgfpointpolar{10}{-3pt}}}}
+    \pgfpathlineto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.4}{\northeast\pgf@xa=\pgf@x\southwest\pgf@x=\pgf@xa}{\northeast}}{\pgfpointpolar{10}{3pt}}}}
+    \pgfpathmoveto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.6}{\northeast\pgf@xa=\pgf@x\southwest\pgf@x=\pgf@xa}{\northeast}}{\pgfpointpolar{10}{-3pt}}}}
+    \pgfpathlineto{\pgf@process{\pgfpointadd{\pgfpointlineattime{.6}{\northeast\pgf@xa=\pgf@x\southwest\pgf@x=\pgf@xa}{\northeast}}{\pgfpointpolar{10}{3pt}}}}
+    \pgfsetlinewidth{0.5pt}
+    \pgfsetstrokecolor{black}
+    \pgfusepath{stroke}
+  }
+}
+\makeatother
index 5590042..fe9ff9e 100644 (file)
@@ -215,7 +215,7 @@ units.
 
 
 \begin{table}[h]
-\caption{Unit Attributes by Unit Kind}
+\caption{Unit attributes by unit kind}
 \label{tab:unitattributesbyunitkind}
 \begin{tabular}{P{5.5cm}|ccccc}
 \hline
@@ -909,13 +909,13 @@ that belongs to that unit.
 As an example, consider a package file, \texttt{demo.dwp}, formed by
 combining \texttt{demo1.dwo} and \texttt{demo2.dwo} from the previous example
 (see Appendix \refersec{app:splitdwarfobjectfileexample}). The
-resulting package file would contain the sections shown in Table
+resulting package file would contain the sections shown in Figure
 \refersec{fig:sectionsandcontributionsinapackagefile}, 
 with contributions from each input file as shown.
+\eb
 
-\begin{table}[h]
-\caption{Sections and contributions in a package file}
-\label{fig:sectionsandcontributionsinapackagefile}
+\begin{figure}[h]
+\bb
 \begin{center}
 \begin{tabular}{P{4.7cm}|P{8cm}}
 \hline
@@ -955,9 +955,13 @@ with contributions from each input file as shown.
 \hline
 \end{tabular}
 \end{center}
-\end{table}
+\caption{Sections and contributions in a package file}
+\label{fig:sectionsandcontributionsinapackagefile}
+\eb
+\end{figure}
 
 \needlines{4}
+\bb
 The \dotdebugabbrevdwo{}, \dotdebuglocdwo{} and \dotdebuglinedwo{}
 sections have been copied over from the two \texttt{.dwo} files as
 individual contributions to the corresponding sections in the
@@ -983,7 +987,7 @@ the correct offset in the merged string table.
 
 The \dotdebugcuindex{} and \dotdebugtuindex{} sections provide a
 directory to these contributions. 
-Table \referfol{fig:examplecuindexsection} shows an example CU
+Figure \referfol{fig:examplecuindexsection} shows an example CU
 index section containing the two compilation units from 
 \texttt{demo1.dwo} and \texttt{demo2.dwo}. The CU index shows that 
 for the compilation unit from \texttt{demo1.dwo}, with \CUsignature{} 
@@ -994,18 +998,19 @@ unit from \texttt{demo2.dwo}, with \CUsignature{}
 section begins at offset 325, and is 673 bytes long.
 
 Likewise, we can find the contributions to the related sections.
-In Figure \referfol{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}, 
+In Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}, 
 we see that the \DWTAGvariable{} DIE at \texttt{7\$} has a
 reference to a location list at offset 0x49 (decimal 73). Because
 this is part of the compilation unit for \texttt{demo2.dwo}, with 
 unit signature \texttt{0xb5f0ecf455e7e97e}, we see that its contribution 
 to \dotdebuglocdwo{} begins at offset 84, so the location list from
-Figure F.8 can be found in \texttt{demo.dwp} at offset 157 (84 + 73) in
+Figure {fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts} 
+can be found in \texttt{demo.dwp} at offset 157 (84 + 73) in
 the combined \dotdebuglocdwo{} section.
+\eb
 
-\begin{table}[h]
-\caption{Example CU index section}
-\label{fig:examplecuindexsection}
+\begin{figure}[h]
+\bb
 \begin{center}
 \begin{tabular}{lrrrrrr}
 \hline \\
@@ -1028,10 +1033,14 @@ the combined \dotdebuglocdwo{} section.
 \\ \hline 
 \end{tabular}
 \end{center}
-\end{table}
+\caption{Example CU index section}
+\label{fig:examplecuindexsection}
+\eb
+\end{figure}
 
 \needlines{4}
-Table \referfol{fig:exampletuindexsection} 
+\bb
+Figure \referfol{fig:exampletuindexsection} 
 shows an example TU index section containing the
 three type units for classes \texttt{Box}, \texttt{Point}, and 
 \texttt{Line}. Each type unit
@@ -1046,10 +1055,10 @@ from \texttt{demo2.dwo}. (The
 sharing of these tables between compilation units and type units
 is typical for some implementations, but is not required by the
 DWARF standard.)
+\eb
 
-\begin{table}[h]
-\caption{Example TU index section}
-\label{fig:exampletuindexsection}
+\begin{figure}[h]
+\bb
 \begin{center}
 \begin{tabular}{lrrrrr}
 \hline
@@ -1075,6 +1084,8 @@ DWARF standard.)
 \hline
 \end{tabular}
 \end{center}
-\end{table}
-
+\caption{Example TU index section}
+\label{fig:exampletuindexsection}
 \eb
+\end{figure}
+