On Windows:
-To Be added
+This Editor has used TeXworks on Windows successfully.
+The About TeXworks tab describes it as "a simple
+environment for edititing, typesetting and previewing
+TeX documents". It is based on MiKTeX, which is Open
+Source (and free). See
+ http://www.tug.org/texworks/
+and/or
+ http://code.google.com/p/texworks/downloads/list
+for full details. It is supported on Windows XP/Vista/7
+and installed easily.
+
+TeXworks presents two windows--one for editing and one
+for viewing the final .pdf. The DWARF document build is
+fast enough to use TeXworks as an "almost WYSIWYG"
+environment.
On Mac OS X:
To Be added
-
+============================
The DWARF5 latex document was first added here May 10, 2012.
The plan is to achieve a complete (insofar as is possible)
identical-to-DWARF4 document (which is referred to as DWARF
4.1). Mark that with a git tag. Then proceed to change
the document with DWARF5 changes.
+
+============================
+
+A limitation of LaTex is that it does not handle multipage
+figures at all (they just run off the bottom of the page).
+It appears the best that can be done is to split figures
+"by hand" into multiple figures. Advise on how to do this
+was found at
+
+www.staff.science.uu.nl/~oostr102/floats/node4.html#SECTION00022000000000000000
+
+and included here:
+
+"There isn't an equivalent longfigure solution, so for figures
+you will usually have to split it yourself. In general this is
+less of a problem. However, the problem you get now is how to
+keep them together, i.e. how to get the parts on subsequent
+pages, and how to get a single entry in the list of figures.
+
+"You will have to split the figure into pieces and put each part
+in a separate figure environment. To keep them together it is
+best to use only the [p] placement, so that they will be put on
+floatpages. As they are bigger than a page this is appropriate.
+The first part would then get a \caption, the subsequent parts
+would be used without a caption. If you want to add a caption-
+like text, enter it as normal text rather than a \caption, so
+that it will not be entered in the list of figures. It may also
+be desirable to issue a \clearpage first, just like we did for
+the longtable, and to encapsulate this in the \afterpage command.
+E.g.
+
+\afterpage{\clearpage\input{myfigure}}
+
+where myfigure.tex contains:
+
+\begin{figure}[p]
+\includegraphics{myfig1.eps}
+\caption{This is a multipage figure}
+\label{fig:xxx}
+\end{figure}
+\begin{figure}[p]
+\includegraphics{myfig2.eps}
+\begin{center}
+Figure~\ref{fig:xxx} (continued)
+\end{center}
+\end{figure}
+
+"You have to make sure that the last part is big enough, otherwise
+LaTeX could decide to postpone it until it has collected some more
+floats. This can be done either by making the figure big enough
+(e.g. by adding some \vspace), or by tweaking the \floatpagefraction
+floatpagefraction parameter.
+
+"If you want your multipage figure to start at a lefthand-side (even-
+numbered) page you can use a test in the \afterpage command (using
+the ifthen package):
+
+\afterpage{\clearpage
+\ifthenelse{\isodd{\value{page}}{\afterpage{\input{myfigure}}} % odd page
+ {\input{myfigure}}}} % even page
+
+"If there are too many floats on the skipped page, this may still fail
+to start your multipage figure on an even page, however."
+
+This is basically the strategy used in the DWARF V4.1 and later documents.
+See especially Appendices D (Examples) and E (Compresion) for numerous
+examples.
+
! for n 1,2,4, or 8 can be used)
\end{alltt}
\end{dwflisting}
-\caption{Duplicate elimination example 1: DWARF section group}
+\caption{Duplicate elimination example \#1: DWARF section group}
\label{fig:duplicateeliminationexample1dwarfsectiongroup}
\end{figure}
\livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}(constant 7)
\end{alltt}
\end{dwflisting}
-\caption{Duplicate elimination example 2: DWARF section group}
+\caption{Duplicate elimination example \#2: DWARF section group}
\label{fig:duplicateeliminationexample2dwarfsectiongroup}
\end{figure}
...
\end{alltt}
\end{dwflisting}
-\caption{Duplicate elimination example 2: companion DWARF }
+\caption{Duplicate elimination example \#2: companion DWARF }
\label{fig:duplicateeliminationexample2companiondwarf}
\end{figure}
\dwf, Version 4.1 (Draft)
-Copyright \copyright 2012 \dwf\ Committee
+Copyright \copyright 2010, 2013 \dwf\ Committee
Permission is granted to copy,
distribute and/or modify this document under the terms of the
The differences between the 32\dash\ and 64\dash bit
DWARF formats are
detailed in the following:
-
-
\begin{enumerate}[1.]
-
\item In the 32\dash bit DWARF format, an
\addtoindex{initial length field}
(see
-\documentclass[12pt,letterpaper,oneside]{memoir}
+\documentclass[12pt,letterpaper,twoside]{memoir}
% for debugging, add 'draft' (without quotes) to the [] document class list.
% If draft is in the document class list, pix are just suggested
% by an outline, the pic does not appear as a picture.
\usepackage{listings}
\usepackage{alltt}
\lstset{ %
-language=C++, % choose the language of the code
+language={}, % choose the language of the code
basicstyle=\footnotesize, % the size of the fonts that are used for the code
numbers=left, % where to put the line-numbers
numberstyle=\footnotesize, % the size of the fonts that are used for the line-numbers
\usepackage{amsmath} % Provides \nobreakdash
\usepackage{graphicx} % For pictures
-\usepackage{longtable}
+\usepackage{longtable} % For multipage tables
\usepackage{varioref} % defines \vref
% \textregistered is the trademark symbol
\usepackage[headheight=16pt,paper=letterpaper]{geometry}
\setlength{\headheight}{15pt} % avoids warning from latex
-\usepackage{epic} % For eepic package
-\usepackage{eepic} % For the diagram of section relationships
-\usepackage{makeidx}
+\usepackage{ifthen} % For conditional processing
+\usepackage{changepage} % For odd/even page checks
+\usepackage{epic} % For eepic package
+\usepackage{eepic} % For the diagram of section relationships
+\usepackage{makeidx} % For making an index
% hyperref must be the last package listed.
% The hyperref settings helps hypertext get right links in the
% pdf of the index.
-\usepackage[plainpages=false,pdfpagelabels,pagebackref]{hyperref} % Lets us generate colored active links inside a pdf.
+\usepackage[plainpages=false,pdfpagelabels,pagebackref]{hyperref} % Lets us generate colored active links inside a pdf.
\makeindex % This and the makeidx package allow \index to create index entries.
-\newcommand{\docdate}{20 January 2013}
+\newcommand{\docdate}{28 January 2013}
\newcommand{\dwf}{DWARF Debugging Information Format}
\newenvironment{myindentpara}[1]%
pdftitle={\dwf\ Version 4.1}
}
-% An environment to create a listing-like presentation for DWARF examples
+% An environment to create a listing-like (boxed) presentation for DWARF examples
+% Use like \begin{lstlisting}...\end{lstlisting}. Does not do line numbers (boo)
+% but does full LaTex processing within its scope (unlike \verb).
\newsavebox{\savedwf}
\newenvironment{dwflisting}{\begin{lrbox}{\savedwf}
\begin{minipage}{\textwidth}\footnotesize}
{\end{minipage}\end{lrbox}\fbox{\usebox{\savedwf}}}
% A helper to annotate the parts of a multipage figure
\newcommand{\figurepart}[2]{\raggedleft{\textit{\tiny{part #1 of #2}}}}
+
% Generate a page ref.
% use like \refersec{chap:registerbasedaddressing}
%\newcommand{\refersec}[1]{\ref{#1} on page \pageref{#1}}
\newcommand{\addtoindexi}[2]{#1\index{#2}}
\newcommand{\addtoindexx}[1]{\index{#1}}
+% Quote commands that avoid need for inline UTF-8 in these sources
+\newcommand{\doublequote}[1]{\textquotedblleft #1\textquotedblright}
+\newcommand{\singlequote}[1]{\textquoteleft #1\textquoteright}
+
% Better naming for the lowest level section header
\newcommand{\subsubsubsection}[1]{\paragraph{#1}}
% Reduce vertical space at beginning of a list
\setlength{\topsep}{0in}
+\newcommand{\emptypage}{
+ \clearpage
+ \vspace*{4in}
+ \begin{center} \textit{(empty page)} \end{center}
+ }
+
+% A simple rule used in simple tables; default length is 2 inches
+\newcommand{\simplerule}[1][2in]{\rule[4pt]{#1}{1pt}}
+
+% A simple one column table of names; default width is 2 inches
+\newcommand{\simplenametablerule}{\simplerule[2in]}
+\newenvironment{simplenametable}[3][2in]
+ { \begin{table}[H] \caption{#2} \label{#3}
+ \begin{center}
+ \renewcommand{\simplenametablerule}{\simplerule[#1]}
+ \simplenametablerule \\
+ \textbf{Name} \\
+ \simplenametablerule \\
+ }
+ { \simplenametablerule \\
+ \end{center}
+ \end{table}
+ }
+
+%--- Begin the document pages
+%
\begin{document}
-\pagenumbering{roman}
-\pagestyle{empty}
+\frontmatter
+\thispagestyle{empty}
\nonzeroparskip
\setlength{\parindent}{0pt}
%\clearpage
\openany
-\frontmatter
\textmd
\normalsize
\setlength{\headheight}{15pt}
\makeevenfoot{plain}{\docdate}{}{Page \thepage}
\makeoddfoot{plain}{\docdate}{}{Page \thepage}
-\openany
+%\openany
\nonzeroparskip
\setlength{\parindent}{0pt}
\include{copyright}
\include{foreword}
\include{foreword4.1}
+\emptypage
\cleardoublepage
\tableofcontents
\cleardoublepage
\listoftables
+\flushleft
+\chapterstyle{section}
-\mainmatter
-\pagenumbering{arabic}
-
-% Define the levels of sectionality that are numbered.
-\setcounter{secnumdepth}{5}
-
-\nonzeroparskip
\setlength{\parindent}{0pt}
\makepagestyle{fragFirstChPage}
-
-\makeevenhead{fragFirstChPage}{}{}{}
-\makeoddhead{fragFirstChPage}{}{}{}
-\makeoddfoot{fragFirstChPage}{\docdate}{}{Page \thepage}
-\makeevenfoot{fragFirstChPage}{\docdate}{}{Page \thepage}
-
-\aliaspagestyle{chapter}{fragFirstChPage}
-
-
-
-\chapterstyle{section}
-
-
+ \makeevenhead{fragFirstChPage}{}{}{}
+ \makeoddhead{fragFirstChPage}{}{}{}
+ \makeoddfoot{fragFirstChPage}{\docdate}{}{Page \thepage}
+ \makeevenfoot{fragFirstChPage}{\docdate}{}{Page \thepage}
+\nouppercaseheads
\aliaspagestyle{chapter}{fragFirstChPage}
-\flushleft
-
+% ----- Start the main part of the document -----
+\mainmatter
+% Define the levels of sectionality that are numbered.
+\setcounter{secnumdepth}{5}
\include{introduction}
-\include{generaldescription}
+\include{generaldescription} \emptypage
\include{programscope}
-\include{dataobject}
-\include{typeentries}
+\include{dataobject} \emptypage
+\include{typeentries} \emptypage
\include{otherdebugginginformation}
-\include{datarepresentation}
+\include{datarepresentation} \emptypage
% The \appendix toggles us into appendix chapters
\appendix
\include{attributesbytag}
\include{debugsectionrelationships}
-\include{encodingdecoding}
+\include{encodingdecoding} \emptypage
\include{examples}
\include{compression}
\include{sectionversionnumbers}
%\centering
\begin{minipage}{0.4\textwidth}
\centering
-Compilation Unit 1: \addtoindex{.debug\_info}
+Compilation Unit \#1: \addtoindex{.debug\_info}
\begin{framed}
\scriptsize
\begin{alltt}
%
%
\end{framed}
-Compilation Unit 2: \addtoindex{.debug\_info}
+Compilation Unit \#2: \addtoindex{.debug\_info}
\begin{framed}
\scriptsize
\begin{alltt}
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
\label{fig:inliningexample1concreteinstance}
\end{figure}
-\subsection{Alternative 2: Inline OUTER, multiple INNERs}
+\subsection{Alternative \#2: Inline OUTER, multiple INNERs}
\label{app:inlineoutermultiipleinners}
\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
\setlength{\parindent}{0pt}
This version of the DWARF Debugging Information Format is first and foremost
-a re-implementation of the Version 4 document using the \LaTeX document preparation system.
-There are no substantive changes compared to the Version 4 document and very few even minor
-editorial changes other than those mandated by the underlying technology.
+a re-implementation of the Version 4 document using the \LaTeX\
+document preparation system.
+There are no substantive changes compared to the Version 4 document.
+The main presentational change is to convert many figures to proper
+tables and to present most programming language source and DWARF listings
+in a boxed format.
+Otherwise there are very few even minor editorial changes (other than
+those sometimes mandated by the underlying technology).
-If any descrepencies are discovered between these two documents, please bring them to the
-attention of the DWARF Information Format Committee.
+If any substantive descrepancies are discovered between these two documents,
+please bring them to the attention of the DWARF Information Format Committee.
\end{abstract}
\ No newline at end of file
The set of tag names
\addtoindexx{tag names|see{debugging information entry}}
-is listed in Figure \refersec{fig:tagnames}.
+is listed in Figure \refersec{tab:tagnames}.
The debugging information entries they identify are
described in Sections 3, 4 and 5.
% These each need to link to definition page: FIXME
-\begin{figure}[here]
+
+\begin{figure}
+%\begin{table}
+%\begin{tabular}{|}
+%\caption{Tag names}
+%\label{tab:tagnames}
+%\hline
+%\end{tabular)
+%\end{table}
\autorows[0pt]{c}{2}{l}{
\livelink{chap:DWTAGaccessdeclaration}{DW\-\_TAG\-\_access\-\_declaration},
\livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type},
\livelink{chap:DWTAGvolatiletype}{DW\-\_TAG\-\_volatile\-\_type},
\livelink{chap:DWTAGwithstmt}{DW\-\_TAG\-\_with\-\_stmt},
}
-\caption{Tag names}\label{fig:tagnames}
+\caption{Tag names}
+\label{tab:tagnames}
\end{figure}
-The debugging information entry descriptions
+\textit{The debugging information entry descriptions
in Sections 3, 4 and 5 generally include mention of
most, but not necessarily all, of the attributes
that are normally or possibly used with the entry.
debugging information entries, are described in
this section and not necessarily mentioned in all
contexts where they may be appropriate.
-Examples include \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial}, the declaration
-coordinates, and
-\livelink{chap:DWATdescription}{DW\-\_AT\-\_description}, among others.
+Examples include
+\livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial},
+the declaration coordinates, and
+\livelink{chap:DWATdescription}{DW\-\_AT\-\_description},
+among others.}
The debugging information entries are contained
in the \addtoindex{.debug\_info} and
Attribute value forms belong
\addtoindexx{tag names!list of}
-to one of the classes shown in Figure \refersec{tab:classesofattributevalue}.
+to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
\setlength{\extrarowheight}{0.1cm}
\addtoindexx{attributes!list of}
&\livelinki{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}{Virtual function vtable slot}{virtual function vtable slot}\\
\end{longtable}
-\begin{figure}[here]
+\begin{table}[here]
+\caption{Classes of Attribute value}
+\label{tab:classesofattributevalue}
\centering
% Attribute Class entries need a ref to definition point.
\setlength{\extrarowheight}{0.1cm}
-\label{tab:classesofattributevalue}
+
\begin{tabular}{l|p{10cm}} \hline
Attribute Class & General Use and Encoding \\ \hline
\livetargi{chap:address}{address}{address class}
string table.
\end{tabular}
-\caption{Classes of Attribute value}
-\end{figure}
+\end{table}
% It is difficult to get the above table to appear before
% the end of the chapter without a clearpage here.
\livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
attribute, whose
\addtoindexx{accessibility attribute}
-value is a constant drawn from the set of codes listed in Figure
-\ref{fig:accessibilitycodes}.
+value is a constant drawn from the set of codes listed in Table
+\refersec{tab:accessibilitycodes}.
-\begin{figure}[here]
-\begin{description}
-\centering
-\item [\livetarg{chap:DWACCESSpublic}{DW\-\_ACCESS\-\_public}]
-\item [\livetarg{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}]
-\item [\livetarg{chap:DWACCESSprotected}{DW\-\_ACCESS\-\_protected}]
-\end{description}
-\caption{Accessibility codes}
-\label{fig:accessibilitycodes}
-\end{figure}
+\begin{simplenametable}{Accessibility codes}{tab:accessibilitycodes}
+\livetarg{chap:DWACCESSpublic}{DW\-\_ACCESS\-\_public} \\
+\livetarg{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private} \\
+\livetarg{chap:DWACCESSprotected}{DW\-\_ACCESS\-\_protected} \\
+\end{simplenametable}
\section{Visibility of Declarations}
\label{chap:visibilityofdeclarations}
by a \livelink{chap:DWATvisibility}{DW\-\_AT\-\_visibility}
attribute\addtoindexx{visibility attribute}, whose value is a
constant drawn from the set of codes listed in
-Figure \ref{fig:visibilitycodes}.
+Table \refersec{tab:visibilitycodes}.
-\begin{figure}[here]
-\begin{description}
-\centering
-\item [\livetarg{chap:DWVISlocal}{DW\-\_VIS\-\_local}]
-\item [\livetarg{chap:DWVISexported}{DW\-\_VIS\-\_exported}]
-\item [\livetarg{chap:DWVISqualified}{DW\-\_VIS\-\_qualified}]
-\end{description}
-\caption{Visibility codes}
-\label{fig:visibilitycodes}
-\end{figure}
+\begin{simplenametable}{Visibility Codes}{tab:visibilitycodes}
+\livetarg{chap:DWVISlocal}{DW\-\_VIS\-\_local} \\
+\livetarg{chap:DWVISexported}{DW\-\_VIS\-\_exported} \\
+\livetarg{chap:DWVISqualified}{DW\-\_VIS\-\_qualified} \\
+\end{simplenametable}
\section{Virtuality of Declarations}
\label{chap:virtualityofdeclarations}
\livelink{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality}
attribute\addtoindexx{virtuality attribute}, whose value is a constant drawn
from the set of codes listed in
-Figure \ref{fig:virtualitycodes}.
+Table \refersec{tab:virtualitycodes}.
-\begin{figure}[here]
-\begin{description}
-\centering
-\item [\livetarg{chap:DWVIRTUALITYnone}{DW\-\_VIRTUALITY\-\_none}]
-\item [\livetarg{chap:DWVIRTUALITYvirtual}{DW\-\_VIRTUALITY\-\_virtual}]
-\item [\livetarg{chap:DWVIRTUALITYpurevirtual}{DW\-\_VIRTUALITY\-\_pure\-\_virtual}]
-\end{description}
-\caption{Virtuality codes}
-\label{fig:virtualitycodes}
-\end{figure}
+\begin{simplenametable}[2.5in]{Virtuality codes}{tab:virtualitycodes}
+\livetarg{chap:DWVIRTUALITYnone}{DW\-\_VIRTUALITY\-\_none} \\
+\livetarg{chap:DWVIRTUALITYvirtual}{DW\-\_VIRTUALITY\-\_virtual} \\
+\livetarg{chap:DWVIRTUALITYpurevirtual}{DW\-\_VIRTUALITY\-\_pure\-\_virtual} \\
+\end{simplenametable}
\section{Artificial Entries}
\label{chap:artificialentries}
form of the name in the
DWARF \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute,
\addtoindexx{name attribute}
-including the keyword operator (in names such as “operator
-+”), if present. See also
+including the keyword operator (in names such as \doublequote{operator +}),
+if present. See also
Section \refersec{chap:linkagenames} regarding the use
of \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} for
\addtoindex{mangled names}
addresses may also be specified for the
\livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope} attribute.
\addtoindexx{start scope attribute}
+
If an entity has no associated machine code,
none of these attributes are specified.
\chapter{Introduction}
\label{chap:introduction}
+\pagenumbering{arabic}
This document defines a format for describing programs to
facilitate user source level debugging. This description
can be generated by compilers, assemblers and linkage
albeit possibly in a degraded manner.
-\section[Changes Version 3 to 4]{Changes from Version 3 to Version 4}
+\section{Changes from Version 3 to Version 4}
The following is a list of the major changes made to the DWARF Debugging Information
Format since Version 3 was published. The list is not meant to be exhaustive.
\end{itemize}
-\section[Changes Version1 to 2]{Changes from Version 1 to Version 2}
+\section{Changes from Version 1 to Version 2}
\addtoindex{DWARF Version 2}
describes the second generation of debugging
information based on the DWARF format. While
DWARF Git Projects / dwarf-doc.git / commitdiff