This finishes the 'flag' links, which
[dwarf-doc.git] / dwarf5 / latexdoc / programscope.tex
index baafcf0..de8f3e3 100644 (file)
@@ -206,18 +206,19 @@ of base types for a compilation unit that does not itself
 contain such definitions. This allows a consumer, for example,
 to interpret a type conversion to a base type correctly.
 
-\item A \livelink{chap:DWATuseUTF8}{DW\-\_AT\-\_use\-\_UTF8} attribute, which is a flag whose
+\item A \livelink{chap:DWATuseUTF8}{DW\-\_AT\-\_use\-\_UTF8} attribute, 
+which is a \livelink{chap:flag}{flag} whose
 presence indicates that all strings (such as the names of
 declared entities in the source program) are represented
 using the UTF\dash 8 representation 
 (see Section \refersec{datarep:attributeencodings}).
 
 
-\item A \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram} attribute, which is a flag
+\item A \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram} attribute, which is a \livelink{chap:flag}{flag}
 whose presence indicates that the compilation unit contains a
 subprogram that has been identified as the starting function
 of the program. If more than one compilation unit contains
-this flag, any one of them may contain the starting function.
+this \nolink{flag}, any one of them may contain the starting function.
 
 \textit{Fortran has a PROGRAM statement which is used
 to specify and provide a user\dash specified name for the main
@@ -580,7 +581,7 @@ described in Section \refersec{chap:linkagenames}.
 If the name of the subroutine described by an entry with the
 tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} is visible outside of its containing
 compilation unit, that entry has a \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute,
-which is a flag.
+which is a \livelink{chap:flag}{flag}.
 
 \textit{Additional attributes for functions that are members of a
 class or structure are described in 
@@ -588,9 +589,11 @@ Section \refersec{chap:memberfunctionentries}.
 }
 
 A subroutine entry may contain a \livelink{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram}
-attribute which is a flag whose presence indicates that the
+attribute which is 
+a \livelink{chap:flag}{flag} whose presence indicates that the
 subroutine has been identified as the starting function of
-the program.  If more than one subprogram contains this flag,
+the program.  If more than one subprogram contains this 
+\nolink{flag},
 any one of them may be the starting subroutine of the program.
 
 \textit{Fortran has a PROGRAM statement which is used to specify
@@ -650,7 +653,7 @@ those declared using non\dash prototype declarations.
 A subroutine entry declared with a function prototype style
 declaration may have a 
 \livelink{chap:DWATprototyped}{DW\-\_AT\-\_prototyped} attribute, which is
-a flag.
+a \livelink{chap:flag}{flag}.
 
 \textit{The Fortran language allows the keywords elemental, pure
 and recursive to be included as part of the declaration of
@@ -662,16 +665,19 @@ as C where functions support recursion by default.
 }
 
 A subprogram entry may have a \livelink{chap:DWATelemental}{DW\-\_AT\-\_elemental} attribute, which
-is a flag. The attribute indicates whether the subroutine
+is a \livelink{chap:flag}{flag}. 
+The attribute indicates whether the subroutine
 or entry point was declared with the ``elemental'' keyword
 or property.
 
 A subprogram entry may have a \livelink{chap:DWATpure}{DW\-\_AT\-\_pure} attribute, which is
-a flag. The attribute indicates whether the subroutine was
+a \livelink{chap:flag}{flag}. 
+The attribute indicates whether the subroutine was
 declared with the ``pure'' keyword or property.
 
 A subprogram entry may have a \livelink{chap:DWATrecursive}{DW\-\_AT\-\_recursive} attribute, which
-is a flag. The attribute indicates whether the subroutine
+is a \livelink{chap:flag}{flag}. 
+The attribute indicates whether the subroutine
 or entry point was declared with the ``recursive'' keyword
 or property.
 
@@ -742,14 +748,14 @@ The unspecified parameters of a variable parameter list are
 represented by a debugging information entry with the tag
 \livetarg{chap:DWTAGunspecifiedparameters}{DW\-\_TAG\-\_unspecified\-\_parameters}.
 
-The entry for a subroutine that includes a Fortran common block
+The entry for a subroutine that includes a Fortran common \nolink{block}
 has a child entry with the 
 tag \livetarg{chap:DWTAGcommoninclusion}{DW\-\_TAG\-\_common\-\_inclusion}. 
 The
 common inclusion entry has a 
 \livelink{chap:DWATcommonreference}{DW\-\_AT\-\_common\-\_reference} attribute
 whose value is a reference to the debugging information entry
-for the common block being included 
+for the common \nolink{block} being included 
 (see Section \refersec{chap:commonblockentries}).
 
 \subsection{Low-Level Information}
@@ -1024,7 +1030,8 @@ describe the coordinates of the subroutine declaration that
 was inlined, rather they describe the coordinates of the call.
 
 An inlined subroutine entry may have a \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr}
-attribute, which is a flag whose presence indicates that the
+attribute, which is a \livelink{chap:flag}{flag} 
+whose presence indicates that the
 subroutine has been evaluated as a compile\dash time constant. Such
 an entry may also have a \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value} attribute,
 whose value may be of any form that is appropriate for the
@@ -1257,7 +1264,7 @@ the relocated address of the target subprogram.
 \item If the value is of class string, then the value is the
 (possibly mangled) name of the target subprogram.
 
-\item If the value is of class flag, then the value true
+\item If the value is of class \livelink{chap:flag}{flag}, then the value true
 indicates that the containing subroutine is a trampoline but
 that the target subroutine is not known.
 \end{itemize}
@@ -1294,34 +1301,44 @@ which can be assumed to be the target subroutine. }
 \section{Lexical Block Entries}
 \label{chap:lexicalblockentries}
 
-\textit{A lexical block is a bracketed sequence of source statements
+\textit{A lexical \livetargi{chap:lexicalblock}{block}{lexical block} is a bracketed sequence of source statements
 that may contain any number of declarations. In some languages
-(including C and C++), blocks can be nested within other
-blocks to any depth.}
+(including C and C++), \nolink{blocks} can be nested within other
+\nolink{blocks} to any depth.}
 
-A lexical block is represented by a debugging information
+% We do not need to link to the preceeding paragraph.
+A lexical \nolink{block} is represented by a debugging information
 entry with the 
 tag \livetarg{chap:DWTAGlexicalblock}{DW\-\_TAG\-\_lexical\-\_block}.
 
-The lexical block entry may have either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
-\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of attributes or a \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
+The lexical \livetargi{chap:lexicalblockentry}{block}{lexical block entry} entry
+may have 
+either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
+\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of 
+attributes or a \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
 whose values encode the contiguous or non-contiguous address
 ranges, respectively, of the machine instructions generated
-for the lexical block 
+for the lexical \livelink(chap:lexicalblock}{block} 
 (see Section \refersec{chap:codeaddressesandranges}).
 
-If a name has been given to the lexical block in the source
-program, then the corresponding lexical block entry has a
-\livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value is a null-terminated string
-containing the name of the lexical block as it appears in
+If a name has been given to the lexical \livelink(chap:lexicalblock}{block} 
+in the source
+program, then the corresponding 
+lexical \livelink{chap:lexicalblockentry}{block} entry has a
+\livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose 
+value is a null\dash terminated string
+containing the name of the lexical \livelink(chap:lexicalblock}{block} 
+as it appears in
 the source program.
 
 \textit{This is not the same as a C or C++ label (see below).}
 
-The lexical block entry owns debugging information entries that
-describe the declarations within that lexical block. There is
+The lexical \livelink(chap:lexicalblockentry}{block} entry owns 
+debugging information entries that
+describe the declarations within that lexical \livelink(chap:lexicalblock}{block}. 
+There is
 one such debugging information entry for each local declaration
-of an identifier or inner lexical block.
+of an identifier or inner lexical \livelink(chap:lexicalblock}{block}.
 
 \section{Label Entries}
 \label{chap:labelentries}
@@ -1375,33 +1392,43 @@ the with statement.
 \section{Try and Catch Block Entries}
 \label{chap:tryandcatchblockentries}
 
-\textit{In C++ a lexical block may be designated as a ``catch
-block.'' A catch block is an exception handler that handles
-exceptions thrown by an immediately preceding ``try block.''
-A catch block designates the type of the exception that it
+\textit{In C++ a lexical \livelink(chap:lexicalblock}{block} may be 
+designated as a ``catch \nolink{block}.'' 
+A catch \livetargi{chap:catchblock}{block}{catch block} is an 
+exception handler that handles
+exceptions thrown by an immediately 
+preceding ``try \livelink{chap:tryblock}{block}.''
+A catch \livelink{chap:catchblock}{block} 
+designates the type of the exception that it
 can handle.}
 
-A try block is represented by a debugging information entry
+A try \livetargi{chap:tryblock}{block}{try block} is represented 
+by a debugging information entry
 with the tag \livetarg{chap:DWTAGtryblock}{DW\-\_TAG\-\_try\-\_block}.  
-A catch block is represented by
+A catch \livelink{chap:catchblock}{block} is represented by
 a debugging information entry with 
 the tag \livetarg{chap:DWTAGcatchblock}{DW\-\_TAG\-\_catch\-\_block}.
 
-Both try and catch block entries may have either a
+% nolink as we have links just above and do not have a combo link for both
+Both try and catch \nolink{block} entries may have either a
 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of attributes or a
 \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute whose values encode the contiguous
-or non- contiguous address ranges, respectively, of the
-machine instructions generated for the block (see Section
+or non\dash contiguous address ranges, respectively, of the
+machine instructions generated for the \livelink{chap:lexicalblock}{block}
+(see Section
 \refersec{chap:codeaddressesandranges}).
 
-Catch block entries have at least one child entry, an
+Catch \livelink{chap:catchblock}{block} entries have at 
+least one child entry, an
 entry representing the type of exception accepted by
-that catch block. This child entry has one of the tags
+that catch \livelink{chap:catchblock}{block}. 
+This child entry has one of the tags
 \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter} or \livelink{chap:DWTAGunspecifiedparameters}{DW\-\_TAG\-\_unspecified\-\_parameters},
 and will have the same form as other parameter entries.
 
-The siblings immediately following a try block entry are its
-corresponding catch block entries.
+The siblings immediately following 
+a try \livelink{chap:tryblock}{block} entry are its
+corresponding catch \livelink{chap:catchblock}{block} entries.