Began the insertions of live links into the DW_AT_ table,
authorDavid Anderson <davea42@earthlink.net>
Wed, 1 Aug 2012 19:48:19 +0000 (12:48 -0700)
committerDavid Anderson <davea42@earthlink.net>
Wed, 1 Aug 2012 19:48:19 +0000 (12:48 -0700)
following the organization of the DWARF4 document.

READMEindexing has a new comment mentioning a seemingly
obvious thing to do that does not quite work (errors during pdf build).

dwarf5/READMEindexing
dwarf5/latexdoc/dwarf5.tex
dwarf5/latexdoc/generaldescription.tex
dwarf5/latexdoc/programscope.tex
dwarf5/latexdoc/typeentries.tex

index d809894..8645dd2 100644 (file)
@@ -75,12 +75,27 @@ a definition of the term.  The intent is that clicking
 on the word or phrase in the document switches you to
 a display of the definition.
 
+--- Linking of attributes
 Attributes in DWARF may have multiple definition points, so
 for example DW_AT_abstract_origin links one to the attribute table
 and that in turn links to the 3 distinct definitions.
 Other than Attributes though, links are usually directly
 to the definition.
 
+It is critical that the hypertarget and livelink be
+separated to avoid problems with latex. Example:
+
+out\dash of\dash line instance 
+\hypertarget{chap:DWATabstractoriginoutoflineinstance}
+makes use of
+\livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
+
+If the 'makes use of' or some other text is not between
+the hypertarget and hyperlink latex produces output text of
+chap:DWATabstractorigin instead of thinking of it as a link.
+
+--- Linking (continued)
+
 The first argument in a livelink/livetarg/livetargi command
 is a string that must be unique to the target, it is used
 by latex to tie each link to its single target location.
index 28b9994..d38eb84 100644 (file)
@@ -43,7 +43,7 @@ escapeinside={\%*}{*)}  % if you want to add a comment within your code
 \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}{29 May 2012}
+\newcommand{\docdate}{01 August 2012}
 
 \newcommand{\dwf}{DWARF Debugging Information Format}
 \newenvironment{myindentpara}[1]%
index 77f5d7f..6eaac51 100644 (file)
@@ -143,22 +143,23 @@ to one of the classes shown in Figure \refersec{tab:classesofattributevalue}.
   \hline
 \endlastfoot
 \livetarg{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
-&Inline instances of inline subprograms \\
-&Out\dash{} of\dash{} line instances of inline subprograms \\
+&\livelink{chap:DWATabstractorigininlineinstance}{Inline instances of inline subprograms} \\
+% Heren livelink we cannot use \dash or \dash{}.
+&\livelink{chap:DWATabstractoriginoutoflineinstance}{Out-of-line instances of inline subprograms} \\
 \livetarg{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
-&C++ and Ada declarations \\
-&C++ base classes \\
-&C++ inherited members \\
+&\livelink{chap:DWATaccessibilitycandadadeclarations}{C++ and Ada declarations} \\
+&\livelink{chap:DWATaccessibilitycppbaseclasses}{C++ base classes} \\
+&\livelink{chap:DWATaccessibilitycppinheritedmembers}{C++ inherited members} \\
 \livetarg{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class}
-&Pointer or reference types \\
-&Subroutine or subroutine type \\
+&\livelink{chap:DWATadressclasspointerorreferencetypes}{Pointer or reference types} \\
+&\livelink{chap:DWATaddressclasssubroutineorsubroutinetype}{Subroutine or subroutine type} \\
 \livetarg{chap:DWATallocated}{DW\-\_AT\-\_allocated}
-&Allocation status of types \\
+&\livelink{chap:DWATallocatedallocationstatusoftypes}{Allocation status of types} \\
 \livetarg{chap:DWATartificial}{DW\-\_AT\-\_artificial}
-&Objects or types that are not
-actually declared in the source \\
+&\livelink{chap:DWATartificialobjectsortypesthat}{Objects or types that are not
+actually declared in the source} \\
 \livetarg{chap:DWATassociated}{DW\-\_AT\-\_associated} 
-&Association status of types \\
+&\livelink{chap:DWATassociatedassociationstatusoftypes}{Association status of types} \\
 \livetarg{chap:DWATbasetypes}{DW\-\_AT\-\_base\-\_types} 
 &Primitive data types of compilation unit \\
 \livetarg{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} 
@@ -1387,7 +1388,10 @@ the accessibility of an object or of some other program
 entity. The accessibility specifies which classes of other
 program objects are permitted access to the object in question.}
 
-The accessibility of a declaration is represented by a \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} attribute, whose
+The accessibility of a declaration is 
+\hypertarget{chap:DWATaccessibilitycandadadeclarations}
+represented by a 
+\livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} attribute, whose
 value is a constant drawn from the set of codes listed in Figure 
 \ref{fig:accessibilitycodes}.
 
@@ -1460,7 +1464,10 @@ functions.}
 Any debugging information entry representing the
 declaration of an object or type artificially generated by
 a compiler and not explicitly declared by the source program
-may have a \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial} attribute, which is a \livelink{chap:flag}{flag}.
+\hypertarget{chap:DWATartificialobjectsortypesthat}
+may have a 
+\livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial} attribute, 
+which is a \livelink{chap:flag}{flag}.
 
 \section{Segmented Addresses}
 \label{chap:segmentedaddresses}
index e718922..302def5 100644 (file)
@@ -718,8 +718,14 @@ for this purpose, historically the \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_
 was used before the \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} was introduced (in DWARF
 Version 3). There is insufficient reason to change this.}
 
-Subroutines and entry points may also have \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} and
-\livelink{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class} attributes, as appropriate, to specify
+
+Subroutines and entry points 
+\hypertarget{chap:DWATaddressclasssubroutineorsubroutinetype}
+may also have 
+\livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} 
+and
+\livelink{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class} attributes,
+as appropriate, to specify
 which segments the code for the subroutine resides in and
 the addressing mode to be used in calling that subroutine.
 
@@ -1078,7 +1084,10 @@ are not specific to the concrete instance (but present in
 the abstract instance) and need include only attributes that
 are specific to the concrete instance (but omitted in the
 abstract instance). In place of these omitted attributes, each
-concrete inlined instance entry has a \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
+\hypertarget{chap:DWATabstractorigininlineinstance}
+concrete inlined instance entry 
+has a 
+\livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
 attribute that may be used to obtain the missing information
 (indirectly) from the associated abstract instance entry. The
 value of the abstract origin attribute is a reference to the
@@ -1162,7 +1171,12 @@ The DWARF representation of a concrete out\dash of\dash line instance
 of an inlined subroutine is essentially the same as for a
 concrete inlined instance of that subroutine (as described in
 the preceding section). The representation of such a concrete
-out\dash of\dash line instance makes use of \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
+% It is critical that the hypertarget and livelink be
+% separated to avoid problems with latex.
+out\dash of\dash line instance 
+\hypertarget{chap:DWATabstractoriginoutoflineinstance}
+makes use of 
+\livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
 attributes in exactly the same way as they are used for
 a concrete inlined instance (that is, as references to
 corresponding entries within the associated abstract instance
index cf4dbb9..84b6de2 100644 (file)
@@ -312,14 +312,19 @@ a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null-ter
 string containing the modified type name as it appears in
 the source program.
 
-Each of the type modifier entries has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute,
+Each of the type modifier entries has a 
+\livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute,
 whose value is a reference to a debugging information entry
 describing a base type, a user-defined type or another type
 modifier.
 
 A modified type entry describing a pointer or reference
 type (using \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}, \livelink{chap:DWTAGreferencetype}{DW\-\_TAG\-\_reference\-\_type} or
-\livelink{chap:DWTAGrvaluereferencetype}{DW\-\_TAG\-\_rvalue\-\_reference\-\_type}) may have a \livelink{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class}
+\livelink{chap:DWTAGrvaluereferencetype}{DW\-\_TAG\-\_rvalue\-\_reference\-\_type}) 
+may have 
+\hypertarget{chap:DWATadressclasspointerorreferencetypes}
+a 
+\livelink{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class}
 attribute to describe how objects having the given pointer
 or reference type ought to be dereferenced.
 
@@ -479,7 +484,9 @@ be represented by a debugging information entry for a
 multidimensional array.
 
 Other attributes especially applicable to arrays are
-\livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated}, \livelink{chap:DWATassociated}{DW\-\_AT\-\_associated} and \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location},
+\livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated}, 
+\livelink{chap:DWATassociated}{DW\-\_AT\-\_associated} and 
+\livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location},
 which are described in 
 Section \refersec{chap:dynamictypeproperties}. 
 For relevant examples,
@@ -668,8 +675,11 @@ inherited types is the same as the interpretation for data
 members 
 (see Section \refersec{chap:datamemberentries}).  }
 
-An inheritance entry may have a
-\livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} attribute. If no accessibility attribute
+An inheritance entry 
+\hypertarget{chap:DWATaccessibilitycppinheritedmembers}
+may have a
+\livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
+attribute. If no accessibility attribute
 is present, private access is assumed for an entry of a class
 and public access is assumed for an entry of an interface,
 struct or union.
@@ -702,7 +712,10 @@ value is a null-terminated string representing the name used
 in the declaration in the source program, including any class
 or structure qualifiers.
 
-An access declaration entry also has a \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
+An access declaration entry 
+\hypertarget{chap:DWATaccessibilitycppbaseclasses}
+also has a 
+\livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
 attribute describing the declared accessibility of the named
 entities.
 
@@ -1613,10 +1626,12 @@ When this attribute is omitted, the address of the data is
 the same as the address of the object.
 
 \textit{This location description will typically begin with
-\livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address} which loads the address of the
+\livelink{chap:DWOPpushobjectaddress}{DW\-\_OP\-\_push\-\_object\-\_address} 
+which loads the address of the
 object which can then serve as a descriptor in subsequent
-calculation. For an example using \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} for a
-Fortran 90 array, see 
+calculation. For an example using 
+\livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} 
+for a Fortran 90 array, see 
 Appendix \refersec{app:fortran90example}.}
 
 \subsection{Allocation and Association Status}
@@ -1626,14 +1641,21 @@ Appendix \refersec{app:fortran90example}.}
 may be dynamically allocated or associated with a variable
 under explicit program control.}
 
-The \livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated} attribute may optionally be used with any
+\hypertarget{chap:DWATallocatedallocationstatusoftypes}
+The 
+\livelink{chap:DWATallocated}{DW\-\_AT\-\_allocated} 
+attribute may optionally be used with any
 type for which objects of the type can be explicitly allocated
 and deallocated. The presence of the attribute indicates that
 objects of the type are allocatable and deallocatable. The
 integer value of the attribute (see below) specifies whether
-an object of the type is currently allocated or not.
+an object of the type is 
+currently allocated or not.
 
-The \livelink{chap:DWATassociated}{DW\-\_AT\-\_associated} attribute may optionally be used with
+\hypertarget{chap:DWATassociatedassociationstatusoftypes}
+The 
+\livelink{chap:DWATassociated}{DW\-\_AT\-\_associated} attribute 
+may optionally be used with
 any type for which objects of the type can be dynamically
 associated with other objects. The presence of the attribute
 indicates that objects of the type can be associated. The