[PATCH, ADA, DOC] PR 15479: Crossrefs and links

[PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Ralf Wildenhues]

This patch adds proper cross referencing to the Ada manuals.

Right now, there is one crucial limitation to this patch: references
from the Reference Manual to the User Manual have the name gnat_ugn_unw
hard-coded; so it amounts to the wrong thing on VMS, I suppose.  Lifting
this limitation would require some preprocessing of gnat_rm.texi similar
to how gnat_ugn.texi is preprocessed, because texinfo doesn't like
@value's in the info-file-name argument of cross-references.[1]
Should I add that?

Smaller issues regarding this patch:

- gnat_rm.texi, node "Pragma Long_Float", refers to gnatlbr,
  a node which exists in the VMS version of the User's Manual only.
  I suppose this may be fixed along with above.

- gnat_ugn.texi, node "Ada tasks", refers to "tasking support"
  inside GDB.  Should that link to the node "Threads" in gdb?
  FWIW, my gdb does not understand the command "info tasks" at all,
  which is explicitly documented in gnat_ugn.

OK for trunk and 4.3?

Thanks,
Ralf

[1] I've reported that bug to bug-texinfo, along with the bug that
    prevents clickable inter-PDF links when the info-file-name contains
    an underscore.

gcc/ada/ChangeLog:
2008-03-15  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>

	PR documentation/15479
	* gnat_ugn.texi: Fix cross references to the GNAT Reference
	Manual.  Convert links to the GCC, GDB, Emacs, and GNU make
	manuals to be proper texinfo links.
	* gnat_rm.texi: Fix cross references to the GNAT User's Guide,
	hard-coding gnat_ugn_unw as info file name referred to.

diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index 6e7c9dd..b52e2fe 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -462,8 +462,8 @@ Ada 83 compatibility mode.
 By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION},
 but you can override with a compiler switch
 to explicitly specify the language version.
-(Please refer to the section ``Compiling Different Versions of Ada'', in
-@cite{@value{EDITION} User's Guide}, for details on these switches.)
+(Please refer to @ref{Compiling Different Versions of Ada,,, gnat_ugn_unw,
+@value{EDITION} User's Guide}, for details on these switches.)
 Throughout this manual, references to ``Ada'' without a year suffix
 apply to both the Ada 95 and Ada 2005 versions of the language.
 
@@ -630,8 +630,9 @@ See the following documents for further information on GNAT:
 
 @itemize @bullet
 @item
-@cite{GNAT User's Guide}, which provides information on how to use
-the GNAT compiler system.
+@xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn_unw,
+@value{EDITION} User's Guide}, which provides information on how to use the
+GNAT compiler system.
 
 @item
 @cite{Ada 95 Reference Manual}, which contains all reference
@@ -1524,8 +1525,8 @@ the @option{-gnatE} switch had been specified on the command
 line.  If the parameter is @code{Static}, then the default GNAT static
 model is used.  This configuration pragma overrides the setting
 of the command line.  For full details on the elaboration models
-used by the GNAT compiler, see section ``Elaboration Order
-Handling in GNAT'' in the @cite{GNAT User's Guide}.
+used by the GNAT compiler, see @ref{Elaboration Order Handling in GNAT,,,
+gnat_ugn_unw, @value{EDITION} User's Guide}.
 
 @node Pragma Eliminate
 @unnumberedsec Pragma Eliminate
@@ -1980,7 +1981,8 @@ you can construct your own extension unit following the above
 definition.  Note that such a package is a child of @code{System}
 and thus is considered part of the implementation.  To compile
 it you will have to use the appropriate switch for compiling
-system units.  See the GNAT User's Guide for details.
+system units.  @xref{Top, @value{EDITION} User's Guide,,
+gnat_ugn_unw, @value{EDITION} User's Guide}, for details.
 
 @node Pragma External
 @unnumberedsec Pragma External
@@ -2170,9 +2172,9 @@ floating point types declared in the packages @code{Standard} and
 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
 argument may be @code{VAX_Float} to specify the use of the VAX float
 format for the floating-point types in Standard. This requires that
-the standard runtime libraries be recompiled. See the
-description of the @code{GNAT LIBRARY} command in the OpenVMS version
-of the GNAT Users Guide for details on the use of this command.
+the standard runtime libraries be recompiled.  @xref{The GNAT Run-Time
+Library Builder gnatlbr,,, gnat_ugn_unw, @value{EDITION} User's Guide},
+for a description of the @code{GNAT LIBRARY} command.
 
 The two argument form specifies the representation to be used for
 the specified floating-point type. On all systems other than OpenVMS,
@@ -3059,9 +3061,10 @@ type @code{Long_Float} and for floating point type representations with
 @code{digits} specified in the range 7 through 15.
 For further details on this pragma, see the
 @cite{DEC Ada Language Reference Manual}, section 3.5.7b.  Note that to use
-this pragma, the standard runtime libraries must be recompiled.  See the
-description of the @code{GNAT LIBRARY} command in the OpenVMS version
-of the GNAT User's Guide for details on the use of this command.
+this pragma, the standard runtime libraries must be recompiled.
+@xref{The GNAT Run-Time Library Builder gnatlbr,,, gnat_ugn_unw,
+@value{EDITION} User's Guide OpenVMS}, for a description of the
+@code{GNAT LIBRARY} command.
 
 @node Pragma Machine_Attribute
 @unnumberedsec Pragma Machine_Attribute
@@ -3085,8 +3088,10 @@ in GNU C, where @code{@var{attribute_name}} is recognized by the
 target macro @code{TARGET_ATTRIBUTE_TABLE} which is defined for each
 machine.  The optional parameter @var{info} is transformed into an
 identifier, which may make this pragma unusable for some attributes
-(parameter of some attributes must be a number or a string). See the
-GCC manual for further information.  It is not possible to specify
+(parameter of some attributes must be a number or a string).
+@xref{Target Attributes,, Defining target-specific uses of
+@code{__attribute__}, gccint, GNU Compiler Collection (GCC) Internals},
+further information.  It is not possible to specify
 attributes defined by other languages, only attributes defined by the
 machine the code is intended to run on.
 
@@ -3198,8 +3203,8 @@ strict aliasing optimization for the given type.  The form with no
 arguments is a configuration pragma which applies to all access types
 declared in units to which the pragma applies. For a detailed
 description of the strict aliasing optimization, and the situations
-in which it must be suppressed, see section
-``Optimization and Strict Aliasing'' in the @value{EDITION} User's Guide.
+in which it must be suppressed, see @ref{Optimization and Strict
+Aliasing,,, gnat_ugn_unw, @value{EDITION} User's Guide}.
 
 @node Pragma Normalize_Scalars
 @unnumberedsec Pragma Normalize_Scalars
@@ -3459,8 +3464,9 @@ targets that do not normally support the capability.  The version of
 @code{Poll} in this file makes a call to the appropriate runtime routine
 to test for an abort condition.
 
-Note that polling can also be enabled by use of the @option{-gnatP} switch.  See
-the @cite{GNAT User's Guide} for details.
+Note that polling can also be enabled by use of the @option{-gnatP} switch.
+@xref{Switches for gcc,,, gnat_ugn_unw, @value{EDITION} User's Guide}, for
+details.
 
 @node Pragma Profile (Ravenscar)
 @unnumberedsec Pragma Profile (Ravenscar)
@@ -3802,8 +3808,9 @@ A pragma Source_File_Name cannot appear after a
 @ref{Pragma Source_File_Name_Project}.
 
 For more details on the use of the @code{Source_File_Name} pragma,
-see the sections ``Using Other File Names'' and
-``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}.
+@xref{Using Other File Names,,, gnat_ugn_unw, @value{EDITION} User's Guide},
+and @ref{Alternative File Naming Schemes,,, gnat_ugn_unw, @value{EDITION}
+User's Guide}.
 
 @node Pragma Source_File_Name_Project
 @unnumberedsec Pragma Source_File_Name_Project
@@ -3961,8 +3968,8 @@ gcc -c -gnatyl @dots{}
 
 @noindent
 The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the @code{gnaty} switch with no options.  See GNAT User's
-Guide for details.
+to the use of the @code{gnaty} switch with no options.  @xref{Style Checking,,,
+gnat_ugn_unw, @value{EDITION} User's Guide}, for details.
 
 The forms with @code{Off} and @code{On}
 can be used to temporarily disable style checks
@@ -4278,8 +4285,8 @@ declarative part.  The effect is to inhibit strict type-based aliasing
 optimization for the given type.  In other words, the effect is as though
 access types designating this type were subject to pragma No_Strict_Aliasing.
 For a detailed description of the strict aliasing optimization, and the
-situations in which it must be suppressed, see section
-``Optimization and Strict Aliasing'' in the @value{EDITION} User's Guide.
+situations in which it must be suppressed, @xref{Optimization and Strict
+Aliasing,,, gnat_ugn_unw, @value{EDITION} User's Guide}.
 
 @node Pragma Universal_Data
 @unnumberedsec Pragma Universal_Data
@@ -4566,7 +4573,8 @@ control over which warnings are active. The string is a list of letters
 specifying which warnings are to be activated and which deactivated. The
 code for these letters is the same as the string used in the command
 line switch controlling warnings. The following is a brief summary. For
-full details see the GNAT Users Guide:
+full details see @ref{Warning Message Control,,, gnat_ugn_unw,
+@value{EDITION} User's Guide}.
 
 @smallexample
 a   turn on all optional warnings (except d,h,l)
@@ -6383,8 +6391,8 @@ $ mv s-strxdr.adb s-stratt.adb
 @end smallexample
 
 @item
-Rebuild the GNAT run-time library as documented in the
-@cite{GNAT User's Guide}
+Rebuild the GNAT run-time library as documented in
+@ref{GNAT and Libraries,,, gnat_ugn_unw, @value{EDITION} User's Guide}.
 @end enumerate
 
 @unnumberedsec A.1(52): Names of Predefined Numeric Types
@@ -7411,8 +7419,9 @@ provides the binder options @option{-z} and @option{-n} respectively, and in
 this case a list of units can be explicitly supplied to the binder for
 inclusion in the partition (all units needed by these units will also
 be included automatically).  For full details on the use of these
-options, refer to the @cite{GNAT User's Guide} sections on Binding
-and Linking.
+options, refer to @ref{Binding Using gnatbind,,, gnat_ugn_unw, @value{EDITION}
+User's Guide}, and @ref{Linking Using gnatlink,,, gnat_ugn_unw, @value{EDITION}
+User's Guide}.
 
 @sp 1
 @cartouche
@@ -13344,8 +13353,8 @@ obtaining information about exceptions provided by Ada 83 compilers.
 
 @noindent
 Provide a debugging storage pools that helps tracking memory corruption
-problems.  See section ``Finding memory problems with GNAT Debug Pool'' in
-the @cite{GNAT User's Guide}.
+problems.  @xref{The GNAT Debug Pool Facility,,, gnat_ugn_unw,
+@value{EDITION} User's Guide}.
 
 @node GNAT.Debug_Utilities (g-debuti.ads)
 @section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
@@ -14405,10 +14414,8 @@ including machine instructions in a subprogram.
 The two features are similar, and both are closely related to the mechanism
 provided by the asm instruction in the GNU C compiler.  Full understanding
 and use of the facilities in this package requires understanding the asm
-instruction as described in @cite{Using the GNU Compiler Collection (GCC)}
-by Richard Stallman. The relevant section is titled ``Extensions to the C
-Language Family'' @result{} ``Assembler Instructions with C Expression
-Operands''.
+instruction, see @ref{Extended Asm,, Assembler Instructions with C Expression
+Operands, gcc, Using the GNU Compiler Collection (GCC)}.
 
 Calls to the function @code{Asm} and the procedure @code{Asm} have identical
 semantic restrictions and effects as described below.  Both are provided so
@@ -14482,7 +14489,8 @@ the literal value @code{True} to indicate to the code generator that all
 optimizations with respect to the instruction specified should be
 suppressed, and that in particular, for an instruction that has outputs,
 the instruction will still be generated, even if none of the outputs are
-used.  See the full description in the GCC manual for further details.
+used.  @xref{Extended Asm,, Assembler Instructions with C Expression Operands,
+gcc, Using the GNU Compiler Collection (GCC)}, for the full description.
 Generally it is strongly advisable to use Volatile for any ASM statement
 that is missing either input or output operands, or when two or more ASM
 statements appear in sequence, to avoid unwanted optimizations. A warning
@@ -15059,7 +15067,8 @@ This chapter describes the syntax and semantics of project files.
 Project files specify the options to be used when building a system.
 Project files can specify global settings for all tools,
 as well as tool-specific settings.
-See the chapter on project files in the GNAT Users guide for examples of use.
+@xref{Examples of Project Files,,, gnat_ugn_unw, @value{EDITION} User's
+Guide}, for examples of use.
 
 @menu
 * Reserved Words::
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 77a0eed..195ca61 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -923,8 +923,9 @@ documents:
 
 @itemize @bullet
 @item
-@cite{GNAT Reference Manual}, which contains all reference
-material for the GNAT implementation of Ada.
+@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, GNAT
+Reference Manual}, which contains all reference material for the GNAT
+implementation of Ada.
 
 @ifset unw
 @item
@@ -945,18 +946,19 @@ material for the Ada 95 programming language.
 material for the Ada 2005 programming language.
 
 @item
-@cite{Debugging with GDB}
+@xref{Top,, Debugging with GDB, gdb, Debugging with GDB},
 @ifset vms
-, located in the GNU:[DOCS] directory,
+in the GNU:[DOCS] directory,
 @end ifset
-contains all details on the use of the GNU source-level debugger.
+for all details on the use of the GNU source-level debugger.
 
 @item
-@cite{GNU Emacs Manual}
+@xref{Top,, The extensible self-documenting text editor, emacs,
+GNU Emacs Manual},
 @ifset vms
-, located in the GNU:[DOCS] directory if the EMACS kit is installed,
+located in the GNU:[DOCS] directory if the EMACS kit is installed,
 @end ifset
-contains full information on the extensible editor and programming
+for full information on the extensible editor and programming
 environment Emacs.
 
 @end itemize
@@ -2970,8 +2972,8 @@ the pragma import.
 
 @noindent
 Interfacing at the class level can be achieved by using the GNAT specific
-pragmas such as @code{CPP_Constructor}. See the GNAT Reference Manual for
-additional information.
+pragmas such as @code{CPP_Constructor}.  @xref{Interfacing to C++,,,
+gnat_rm, GNAT Reference Manual}, for additional information.
 
 @node Linking a Mixed C++ & Ada Program
 @subsection Linking a Mixed C++ & Ada Program
@@ -3737,9 +3739,10 @@ system configuration. You must have a GNAT cross-compiler built if
 @cindex @option{-B} (@command{gcc})
 Load compiler executables (for example, @code{gnat1}, the Ada compiler)
 from @var{dir} instead of the default location. Only use this switch
-when multiple versions of the GNAT compiler are available. See the
-@command{gcc} manual page for further details. You would normally use the
-@option{-b} or @option{-V} switch instead.
+when multiple versions of the GNAT compiler are available.
+@xref{Directory Options,, Options for Directory Search, gcc, Using the
+GNU Compiler Collection (GCC)}, for further details. You would normally
+use the @option{-b} or @option{-V} switch instead.
 
 @item -c
 @cindex @option{-c} (@command{gcc})
@@ -3981,8 +3984,8 @@ Suppress all checks.
 @cindex @option{-gnatP} (@command{gcc})
 Enable polling. This is required on some systems (notably Windows NT) to
 obtain asynchronous abort and asynchronous transfer of control capability.
-See the description of pragma Polling in the GNAT Reference Manual for
-full details.
+@xref{Pragma Polling,,, gnat_rm, GNAT Reference Manual}, for full
+details.
 
 @item -gnatq
 @cindex @option{-gnatq} (@command{gcc})
@@ -4718,8 +4721,8 @@ A range in a @code{for} loop that is known to be null or might be null
 The following section lists compiler switches that are available
 to control the handling of warning messages. It is also possible
 to exercise much finer control over what warnings are issued and
-suppressed using the GNAT pragma Warnings, which is documented
-in the GNAT Reference manual.
+suppressed using the GNAT pragma Warnings, @xref{Pragma Warnings,,,
+gnat_rm, GNAT Reference manual}.
 
 @table @option
 @c !sort!
@@ -7207,8 +7210,8 @@ the built-in defaults cause these files to be found.
 In addition to the language-defined hierarchies (@code{System}, @code{Ada} and
 @code{Interfaces}), the GNAT distribution provides a fourth hierarchy,
 consisting of child units of @code{GNAT}. This is a collection of generally
-useful types, subprograms, etc. See the @cite{GNAT Reference Manual} for
-further details.
+useful types, subprograms, etc. @xref{The GNAT Library, GNAT Reference Manual,,
+gnat_rm, GNAT Reference Manual}, for further details.
 
 Besides simplifying access to the RTL, a major use of search paths is
 in compiling sources from multiple directories. This can make
@@ -8459,9 +8462,10 @@ system configuration. You must have a GNAT cross-compiler built if
 @cindex @option{-B} (@command{gnatlink})
 Load compiler executables (for example, @code{gnat1}, the Ada compiler)
 from @var{dir} instead of the default location. Only use this switch
-when multiple versions of the GNAT compiler are available. See the
-@command{gcc} manual page for further details. You would normally use the
-@option{-b} or @option{-V} switch instead.
+when multiple versions of the GNAT compiler are available.
+@xref{Directory Options,,, gcc, The GNU Compiler Collection},
+for further details. You would normally use the @option{-b} or
+@option{-V} switch instead.
 
 @item --GCC=@var{compiler_name}
 @cindex @option{--GCC=compiler_name} (@command{gnatlink})
@@ -9500,7 +9504,8 @@ and a time optimization on the same compile command.
 Since the precise set of optimizations done at each level will vary from
 release to release (and sometime from target to target), it is best to think
 of the optimization settings in general terms.
-The @cite{Using GNU GCC} manual contains details about
+@xref{Optimize Options,, Options That Control Optimization, gcc, Using
+the GNU Compiler Collection (GCC)}, for details about
 ^the @option{-O} settings and a number of @option{-f} options that^how to^
 individually enable or disable specific optimizations.
 
@@ -9776,8 +9781,9 @@ to work. Examples of switches in this category are
 @option{-funroll-loops} and
 the various target-specific @option{-m} options (in particular, it has been
 observed that @option{-march=pentium4} can significantly improve performance
-on appropriate machines). For full details of these switches, see the
-@command{gcc} manual.
+on appropriate machines). For full details of these switches, see
+@ref{Submodel Options,, Hardware Models and Configurations, gcc, Using
+the GNU Compiler Collection (GCC)}.
 
 @node Optimization and Strict Aliasing
 @subsection Optimization and Strict Aliasing
@@ -10036,7 +10042,8 @@ subprograms that are declared but never called. By placing the list of
 @code{Eliminate} pragmas in the GNAT configuration file @file{gnat.adc} and
 recompiling your program, you may decrease the size of its executable,
 because the compiler will not generate the code for 'eliminated' subprograms.
-See GNAT Reference Manual for more information about this pragma.
+@xref{Pragma Eliminate,,, gnat_rm, GNAT Reference Manual}, for more
+information about this pragma.
 
 @code{gnatelim} needs as its input data the name of the main subprogram
 and a bind file for a main subprogram.
@@ -10703,10 +10710,10 @@ unit will be skipped.
 @noindent
 Configuration pragmas include those pragmas described as
 such in the Ada Reference Manual, as well as
-implementation-dependent pragmas that are configuration pragmas. See the
-individual descriptions of pragmas in the @cite{GNAT Reference Manual} for
-details on these additional GNAT-specific configuration pragmas. Most
-notably, the pragma @code{Source_File_Name}, which allows
+implementation-dependent pragmas that are configuration pragmas.
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
+for details on these additional GNAT-specific configuration pragmas.
+Most notably, the pragma @code{Source_File_Name}, which allows
 specifying non-default names for source files, is a configuration
 pragma. The following is a complete list of configuration pragmas
 recognized by GNAT:
@@ -11214,7 +11221,8 @@ that might be used by the developers.
 The next section introduces the main features of GNAT's project facility
 through a sequence of examples; subsequent sections will present the syntax
 and semantics in more detail. A more formal description of the project
-facility appears in the GNAT Reference Manual.
+facility appears in @ref{Project File Reference,,, gnat_rm, GNAT
+Reference Manual}.
 
 @c *****************************
 @c * Examples of Project Files *
@@ -18649,9 +18657,9 @@ to use it.
 
 @noindent
 This chapter offers some examples of makefiles that solve specific
-problems. It does not explain how to write a makefile (see the GNU make
-documentation), nor does it try to replace the @command{gnatmake} utility
-(@pxref{The GNAT Make Program gnatmake}).
+problems. It does not explain how to write a makefile (@pxref{Top,, GNU
+make, make, GNU @code{make}}), nor does it try to replace the
+@command{gnatmake} utility (@pxref{The GNAT Make Program gnatmake}).
 
 All the examples in this section are specific to the GNU version of
 make. Although @command{make} is a standard utility, and the basic language
@@ -19962,15 +19970,15 @@ To record compiler style checks, use the rule named
 @code{Style_Checks}. A parameter of this rule can be either @code{All_Checks},
 which enables all the style checks, or a string that has exactly the same
 structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma
-@code{Style_Checks} (for further information about this pragma, please
-refer to the @cite{@value{EDITION} Reference Manual}).
+@code{Style_Checks} (for further information about this pragma,
+@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}).
 
 @item Warnings
 To record compiler warnings (@pxref{Warning Message Control}), use the rule
 named @code{Warnings} with a parameter that is a valid
 @i{static_string_expression} argument of GNAT pragma @code{Warnings}
-(for further information about this pragma, please
-refer to the @cite{@value{EDITION} Reference Manual}).
+(for further information about this pragma, @pxref{Pragma Warnings,,,
+gnat_rm, GNAT Reference Manual}).
 
 @end table
 
@@ -20380,8 +20388,8 @@ checked and sets the checks for all the specified pragmas
 ON. @emph{Pragma_Name} is treated as a name of a pragma. If it
 does not correspond to any pragma name defined in the Ada
 standard or to the name of a GNAT-specific pragma defined
-in the GNAT Reference Manual, it is treated as the name of
-unknown pragma.
+in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
+Manual}, it is treated as the name of unknown pragma.
 
 @item @code{GNAT}
 All the GNAT-specific pragmas are detected; this sets
@@ -20398,10 +20406,9 @@ Removes the specified pragma from the set of pragmas to be
 checked without affecting checks for
 other pragmas. @emph{Pragma_Name} is treated as a name
 of a pragma. If it does not correspond to any pragma
-defined in the Ada standard or to any name defined in the
-GNAT Reference Manual,
-this option is treated as turning OFF detection of all
-unknown pragmas.
+defined in the Ada standard or to any name defined in
+@ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
+this option is treated as turning OFF detection of all unknown pragmas.
 
 @item GNAT
 Turn OFF detection of all GNAT-specific pragmas
@@ -21947,11 +21954,11 @@ and in particular is capable of debugging Ada programs compiled with
 GNAT. The latest versions of @code{GDB} are Ada-aware and can handle
 complex Ada data structures.
 
-The manual @cite{Debugging with GDB}
+@xref{Top,, Debugging with GDB, gdb, Debugging with GDB},
 @ifset vms
-, located in the GNU:[DOCS] directory,
+located in the GNU:[DOCS] directory,
 @end ifset
-contains full details on the usage of @code{GDB}, including a section on
+for full details on the usage of @code{GDB}, including a section on
 its usage on programs. This manual should be consulted for full
 details. The section that follows is a brief introduction to the
 philosophy and use of @code{GDB}.
@@ -22031,12 +22038,12 @@ describes some of the additional commands that can be given to @code{GDB}.
 @section Introduction to GDB Commands
 
 @noindent
-@code{GDB} contains a large repertoire of commands. The manual
-@cite{Debugging with GDB}
+@code{GDB} contains a large repertoire of commands.  @xref{Top,,
+Debugging with GDB, gdb, Debugging with GDB},
 @ifset vms
-(located in the GNU:[DOCS] directory)
+located in the GNU:[DOCS] directory,
 @end ifset
-includes extensive documentation on the use
+for extensive documentation on the use
 of these commands, together with examples of their use. Furthermore,
 the command @command{help} invoked from within GDB activates a simple help
 facility which summarizes the available commands and their options.
@@ -22131,8 +22138,8 @@ The above list is a very short introduction to the commands that
 @code{GDB} provides. Important additional capabilities, including conditional
 breakpoints, the ability to execute command sequences on a breakpoint,
 the ability to debug at the machine instruction level and many other
-features are described in detail in @cite{Debugging with GDB}.
-Note that most commands can be abbreviated
+features are described in detail in @ref{Top,, Debugging with GDB, gdb,
+Debugging with GDB}.  Note that most commands can be abbreviated
 (for example, c for continue, bt for backtrace).
 
 @node Using Ada Expressions
@@ -22165,7 +22172,8 @@ packages, thus making it unnecessary to fully qualify most names with
 their packages, regardless of context. Where this causes ambiguity,
 @code{GDB} asks the user's intent.
 
-For details on the supported Ada syntax, see @cite{Debugging with GDB}.
+For details on the supported Ada syntax, see @ref{Ada,, Debugging with
+GDB, gdb, Debugging with GDB}.
 
 @node Calling User-Defined Subprograms
 @section Calling User-Defined Subprograms
@@ -22325,7 +22333,7 @@ perturbed.
 
 @noindent
 For more detailed information on the tasking support,
-see @cite{Debugging with GDB}.
+see @ref{Top,, Debugging with GDB, gdb, Debugging with GDB}.
 
 @node Debugging Generic Units
 @section Debugging Generic Units
@@ -22984,9 +22992,9 @@ GNAT always follows the Alpha implementation.
 
 For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
 attributes are recognized, although only a subset of them can sensibly
-be implemented.  The description of pragmas in the
-@cite{GNAT Reference Manual} indicates whether or not they are applicable
-to non-VMS systems.
+be implemented.  The description of pragmas in
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
+indicates whether or not they are applicable to non-VMS systems.
 
 @menu
 * Ada Language Compatibility::
@@ -23343,7 +23351,8 @@ for Q'Address use Q_Address;
 @noindent
 which will be accepted by GNAT (and other Ada compilers), and is also
 compatible with Ada 83. A fuller description of the restrictions
-on address specifications is found in the @cite{GNAT Reference Manual}.
+on address specifications is found in @ref{Top, GNAT Reference Manual,
+About This Guide, gnat_rm, GNAT Reference Manual}.
 
 @node Other Representation Clauses
 @subsection Other Representation Clauses
@@ -23430,8 +23439,8 @@ pragma Extend_System (Aux_DEC);
 
 @noindent
 The pragma @code{Extend_System} is a configuration pragma that
-is most conveniently placed in the @file{gnat.adc} file. See the
-@cite{GNAT Reference Manual} for further details.
+is most conveniently placed in the @file{gnat.adc} file. @xref{Pragma
+Extend_System,,, gnat_rm, GNAT Reference Manual} for further details.
 
 HP Ada does not allow the recompilation of the package
 @code{SYSTEM}. Instead HP Ada provides several pragmas
@@ -23462,8 +23471,8 @@ are virtually identical to those provided by the HP Ada 83 package
 @code{TO_ADDRESS}
 function for type @code{UNSIGNED_LONGWORD} is changed to
 @code{TO_ADDRESS_LONG}.
-See the @cite{GNAT Reference Manual} for a discussion of why this change was
-necessary.
+@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual} for a
+discussion of why this change was necessary.
 
 @noindent
 The version of @code{TO_ADDRESS} taking a @i{universal_integer} argument
@@ -23792,8 +23801,9 @@ GNAT also supplies a number of implementation-defined pragmas as follows:
 @end itemize
 
 @noindent
-For full details on these GNAT implementation-defined pragmas, see
-the GNAT Reference Manual.
+For full details on these GNAT implementation-defined pragmas,
+see @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
+Manual}.
 
 @menu
 * Restrictions on the Pragma INLINE::
@@ -24035,8 +24045,7 @@ Interfacing to C with GNAT, you can use the above approach
 described for HP Ada or the facilities of Annex B of
 the @cite{Ada Reference Manual} (packages @code{INTERFACES.C},
 @code{INTERFACES.C.STRINGS} and @code{INTERFACES.C.POINTERS}). For more
-information, see the section ``Interfacing to C'' in the
-@cite{GNAT Reference Manual}.
+information, see @ref{Interfacing to C,,, gnat_rm, GNAT Reference Manual}.
 
 The @option{-gnatF} qualifier forces default and explicit
 @code{External_Name} parameters in pragmas @code{Import} and @code{Export}
@@ -24407,8 +24416,8 @@ by the @cite{Ada Reference Manual}.
 
 For further information on how GNAT interfaces to the file
 system or how I/O is implemented in programs written in
-mixed languages, see the chapter ``Implementation of the
-Standard I/O'' in the @cite{GNAT Reference Manual}.
+mixed languages, see @ref{Implementation of the Standard I/O,,,
+gnat_rm, GNAT Reference Manual}.
 This chapter covers the following:
 @itemize @bullet
 @item  Standard I/O packages
@@ -27739,8 +27748,9 @@ a pragma @code{Assert} that can be used for such tests. This pragma is modeled
 @cindex pragma @code{Assert}
 on the @code{Assert} pragma that has always been available in GNAT, so this
 feature may be used with GNAT even if you are not using Ada 2005 features.
-The use of pragma @code{Assert} is described in the
-@cite{GNAT Reference Manual}, but as an example, the last test could be written:
+The use of pragma @code{Assert} is described in
+@ref{Pragma Assert,,, gnat_rm, GNAT Reference Manual}, but as an
+example, the last test could be written:
 
 @smallexample @c ada
 pragma Assert (Temperature <= 999.0, "Temperature Crazy");
@@ -28206,7 +28216,8 @@ from which it generates a sequence of assembly language instructions.
 
 The examples in this chapter will illustrate several of the forms
 for invoking @code{Asm}; a complete specification of the syntax
-is found in the @cite{GNAT Reference Manual}.
+is found in @ref{Machine Code Insertions,,, gnat_rm, GNAT Reference
+Manual}.
 
 Under the standard GNAT conventions, the @code{Nothing} procedure
 should be in a file named @file{nothing.adb}.
@@ -29086,11 +29097,11 @@ transition from certain Ada 83 compilers.
 @noindent
 Ada compilers are allowed to supplement the language-defined pragmas, and
 these are a potential source of non-portability.  All GNAT-defined pragmas
-are described in the GNAT Reference Manual, and these include several that
-are specifically intended to correspond to other vendors' Ada 83 pragmas.
+are described in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT
+Reference Manual}, and these include several that are specifically
+intended to correspond to other vendors' Ada 83 pragmas.
 For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful.
-For
-compatibility with HP Ada 83, GNAT supplies the pragmas
+For compatibility with HP Ada 83, GNAT supplies the pragmas
 @code{Extend_System}, @code{Ident}, @code{Inline_Generic},
 @code{Interface_Name}, @code{Passive}, @code{Suppress_All},
 and @code{Volatile}.
@@ -29105,9 +29116,9 @@ relevant in a GNAT context and hence are not otherwise implemented.
 @subsection Implementation-defined attributes
 
 Analogous to pragmas, the set of attributes may be extended by an
-implementation.  All GNAT-defined attributes are described in the
-@cite{GNAT Reference Manual}, and these include several that are specifically
-intended
+implementation.  All GNAT-defined attributes are described in
+@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference
+Manual}, and these include several that are specifically intended
 to correspond to other vendors' Ada 83 attributes.  For migrating from VADS,
 the attribute @code{VADS_Size} may be useful.  For compatibility with HP
 Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and
@@ -29383,8 +29394,8 @@ Overview and Comparison on HP Platforms}.
 
 For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
 attributes are recognized, although only a subset of them can sensibly
-be implemented.  The description of pragmas in the
-@cite{GNAT Reference Manual}
+be implemented.  The description of pragmas in @ref{Implementation
+Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
 indicates whether or not they are applicable to non-VMS systems.
 @end ifclear
 

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Arnaud Charlet]

> Right now, there is one crucial limitation to this patch: references
> from the Reference Manual to the User Manual have the name gnat_ugn_unw
> hard-coded; so it amounts to the wrong thing on VMS, I suppose.  Lifting
> this limitation would require some preprocessing of gnat_rm.texi similar
> to how gnat_ugn.texi is preprocessed, because texinfo doesn't like
> @value's in the info-file-name argument of cross-references.[1]
> Should I add that?

Hard coding the name is indeed not desirable and should be addressed before
doing this change.

> Smaller issues regarding this patch:
> 
> - gnat_rm.texi, node "Pragma Long_Float", refers to gnatlbr,
>   a node which exists in the VMS version of the User's Manual only.
>   I suppose this may be fixed along with above.

Sounds like a good idea.

> - gnat_ugn.texi, node "Ada tasks", refers to "tasking support"
>   inside GDB.  Should that link to the node "Threads" in gdb?

No, the ref is indeed to Ada tasks.

>   FWIW, my gdb does not understand the command "info tasks" at all,
>   which is explicitly documented in gnat_ugn.

That's indeed related. I do not know the state of the Ada specific
documentation in gdb, so this refers to GNAt additions that may not yet be
at the FSF, although will appear at some point if not already.

> OK for trunk and 4.3?

Not in the current form.

I'd suggest resubmitting a patch with the tricky parts left aside for now,
so that 90% of your changes can be OKed. You can then work on the
remaining 10% when you get a chance.

Arno

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Ralf Wildenhues]

Hello Arnaud,

* Arnaud Charlet wrote on Sun, Mar 16, 2008 at 07:22:10PM CET:
> > Right now, there is one crucial limitation to this patch: references
> > from the Reference Manual to the User Manual have the name gnat_ugn_unw
> > hard-coded; [...]

> Hard coding the name is indeed not desirable and should be addressed before
> doing this change.

OK.  In the patch below I did that.  However, for now I did not to
rename the output file to gnat_rm_{unw,vms}.  Please say so if you want
that, too.

> > - gnat_ugn.texi, node "Ada tasks", refers to "tasking support"
> >   inside GDB.  Should that link to the node "Threads" in gdb?
> 
> No, the ref is indeed to Ada tasks.

So I left that to be a general link to the GDB manual for now.

OK for trunk and 4.3?

Thanks for the review,
Ralf

gcc/ada/ChangeLog:
2008-03-16  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>

	PR documentation/15479
	* gnat_ugn.texi: Fix cross references to the GNAT Reference
	Manual.  Convert links to the GCC, GDB, Emacs, and GNU make
	manuals to be proper texinfo links.
	* gnat_rm.texi: Fix cross references to the GNAT User's Guide.
	* Make-lang.in (doc/gnat_rm.texi): New, create from
	ada/gnat_rm.texi using xgnatugn.
	(doc/gnat_rm.info, doc/gnat_rm.dvi, doc/gnat_rm.pdf): Adjust.

Index: gcc/ada/Make-lang.in
===================================================================
--- gcc/ada/Make-lang.in	(Revision 133270)
+++ gcc/ada/Make-lang.in	(Arbeitskopie)
@@ -412,7 +412,13 @@
             -I$(srcdir)/ada -o $@ $<; \
 	else true; fi
 
-doc/gnat_rm.info: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi	\
+doc/gnat_rm.texi: $(srcdir)/ada/gnat_rm.texi $(srcdir)/ada/ug_words \
+  $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
+	$(MAKE) ada/doctools/xgnatugn$(build_exeext)
+	ada/doctools/xgnatugn unw $(srcdir)/ada/gnat_rm.texi \
+	   $(srcdir)/ada/ug_words doc/gnat_rm.texi
+
+doc/gnat_rm.info: doc/gnat_rm.texi $(gcc_docdir)/include/fdl.texi \
    $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
 	if [ x$(BUILD_INFO) = xinfo ]; then \
 	  rm -f $(@)*; \
@@ -464,7 +470,7 @@
 	$(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
 	$(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $<
 
-doc/gnat_rm.dvi: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi	\
+doc/gnat_rm.dvi: doc/gnat_rm.texi $(gcc_docdir)/include/fdl.texi	\
 	$(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
 	$(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $<
 
@@ -475,7 +481,7 @@
 	$(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
 	$(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $<
 
-doc/gnat_rm.pdf: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi	\
+doc/gnat_rm.pdf: doc/gnat_rm.texi $(gcc_docdir)/include/fdl.texi	\
 	$(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
 	$(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $<
 
Index: gcc/ada/gnat_rm.texi
===================================================================
--- gcc/ada/gnat_rm.texi	(Revision 133270)
+++ gcc/ada/gnat_rm.texi	(Arbeitskopie)
@@ -460,10 +460,10 @@
 @value{EDITION} implements Ada 95 and Ada 2005, and it may also be invoked in
 Ada 83 compatibility mode.
 By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION},
-but you can override with a compiler switch
-to explicitly specify the language version.
-(Please refer to the section ``Compiling Different Versions of Ada'', in
-@cite{@value{EDITION} User's Guide}, for details on these switches.)
+but you can override with a compiler switch to explicitly specify the
+language version.  (Please refer to @ref{Compiling Different Versions of
+Ada,,, gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}, for details on
+these switches.)
 Throughout this manual, references to ``Ada'' without a year suffix
 apply to both the Ada 95 and Ada 2005 versions of the language.
 
@@ -630,8 +630,9 @@
 
 @itemize @bullet
 @item
-@cite{GNAT User's Guide}, which provides information on how to use
-the GNAT compiler system.
+@xref{Top, @value{EDITION} User's Guide, About This Guide,
+gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}, which provides
+information on how to use the GNAT compiler system.
 
 @item
 @cite{Ada 95 Reference Manual}, which contains all reference
@@ -1524,8 +1525,8 @@
 line.  If the parameter is @code{Static}, then the default GNAT static
 model is used.  This configuration pragma overrides the setting
 of the command line.  For full details on the elaboration models
-used by the GNAT compiler, see section ``Elaboration Order
-Handling in GNAT'' in the @cite{GNAT User's Guide}.
+used by the GNAT compiler, see @ref{Elaboration Order Handling in
+GNAT,,, gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}.
 
 @node Pragma Eliminate
 @unnumberedsec Pragma Eliminate
@@ -1980,7 +1981,8 @@
 definition.  Note that such a package is a child of @code{System}
 and thus is considered part of the implementation.  To compile
 it you will have to use the appropriate switch for compiling
-system units.  See the GNAT User's Guide for details.
+system units.  @xref{Top, @value{EDITION} User's Guide,,
+gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}, for details.
 
 @node Pragma External
 @unnumberedsec Pragma External
@@ -2170,9 +2172,12 @@
 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
 argument may be @code{VAX_Float} to specify the use of the VAX float
 format for the floating-point types in Standard. This requires that
-the standard runtime libraries be recompiled. See the
-description of the @code{GNAT LIBRARY} command in the OpenVMS version
-of the GNAT Users Guide for details on the use of this command.
+the standard runtime libraries be recompiled.
+@ifset vms
+@xref{The GNAT Run-Time Library Builder gnatlbr,,, gnat_ugn_^unw^vms^,
+@value{EDITION} User's Guide}, for a description of the @code{GNAT
+LIBRARY} command.
+@end ifset
 
 The two argument form specifies the representation to be used for
 the specified floating-point type. On all systems other than OpenVMS,
@@ -3059,9 +3064,12 @@
 @code{digits} specified in the range 7 through 15.
 For further details on this pragma, see the
 @cite{DEC Ada Language Reference Manual}, section 3.5.7b.  Note that to use
-this pragma, the standard runtime libraries must be recompiled.  See the
-description of the @code{GNAT LIBRARY} command in the OpenVMS version
-of the GNAT User's Guide for details on the use of this command.
+this pragma, the standard runtime libraries must be recompiled.
+@ifset vms
+@xref{The GNAT Run-Time Library Builder gnatlbr,,, gnat_ugn_^unw^vms^,
+@value{EDITION} User's Guide OpenVMS}, for a description of the
+@code{GNAT LIBRARY} command.
+@end ifset
 
 @node Pragma Machine_Attribute
 @unnumberedsec Pragma Machine_Attribute
@@ -3085,8 +3093,10 @@
 target macro @code{TARGET_ATTRIBUTE_TABLE} which is defined for each
 machine.  The optional parameter @var{info} is transformed into an
 identifier, which may make this pragma unusable for some attributes
-(parameter of some attributes must be a number or a string). See the
-GCC manual for further information.  It is not possible to specify
+(parameter of some attributes must be a number or a string).
+@xref{Target Attributes,, Defining target-specific uses of
+@code{__attribute__}, gccint, GNU Compiler Collection (GCC) Internals},
+further information.  It is not possible to specify
 attributes defined by other languages, only attributes defined by the
 machine the code is intended to run on.
 
@@ -3198,8 +3208,8 @@
 arguments is a configuration pragma which applies to all access types
 declared in units to which the pragma applies. For a detailed
 description of the strict aliasing optimization, and the situations
-in which it must be suppressed, see section
-``Optimization and Strict Aliasing'' in the @value{EDITION} User's Guide.
+in which it must be suppressed, see @ref{Optimization and Strict
+Aliasing,,, gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}.
 
 @node Pragma Normalize_Scalars
 @unnumberedsec Pragma Normalize_Scalars
@@ -3459,8 +3469,9 @@
 @code{Poll} in this file makes a call to the appropriate runtime routine
 to test for an abort condition.
 
-Note that polling can also be enabled by use of the @option{-gnatP} switch.  See
-the @cite{GNAT User's Guide} for details.
+Note that polling can also be enabled by use of the @option{-gnatP} switch.
+@xref{Switches for gcc,,, gnat_ugn_^unw^vms^, @value{EDITION} User's
+Guide}, for details.
 
 @node Pragma Profile (Ravenscar)
 @unnumberedsec Pragma Profile (Ravenscar)
@@ -3802,8 +3813,9 @@
 @ref{Pragma Source_File_Name_Project}.
 
 For more details on the use of the @code{Source_File_Name} pragma,
-see the sections ``Using Other File Names'' and
-``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}.
+@xref{Using Other File Names,,, gnat_ugn_^unw^vms^, @value{EDITION}
+User's Guide}, and @ref{Alternative File Naming Schemes,,,
+gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}.
 
 @node Pragma Source_File_Name_Project
 @unnumberedsec Pragma Source_File_Name_Project
@@ -3961,8 +3973,9 @@
 
 @noindent
 The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the @code{gnaty} switch with no options.  See GNAT User's
-Guide for details.
+to the use of the @code{gnaty} switch with no options.  @xref{Style
+Checking,,, gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}, for
+details.
 
 The forms with @code{Off} and @code{On}
 can be used to temporarily disable style checks
@@ -4278,8 +4291,8 @@
 optimization for the given type.  In other words, the effect is as though
 access types designating this type were subject to pragma No_Strict_Aliasing.
 For a detailed description of the strict aliasing optimization, and the
-situations in which it must be suppressed, see section
-``Optimization and Strict Aliasing'' in the @value{EDITION} User's Guide.
+situations in which it must be suppressed, @xref{Optimization and Strict
+Aliasing,,, gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}.
 
 @node Pragma Universal_Data
 @unnumberedsec Pragma Universal_Data
@@ -4566,7 +4579,8 @@
 specifying which warnings are to be activated and which deactivated. The
 code for these letters is the same as the string used in the command
 line switch controlling warnings. The following is a brief summary. For
-full details see the GNAT Users Guide:
+full details see @ref{Warning Message Control,,, gnat_ugn_^unw^vms^,
+@value{EDITION} User's Guide}.
 
 @smallexample
 a   turn on all optional warnings (except d,h,l)
@@ -6383,8 +6397,9 @@
 @end smallexample
 
 @item
-Rebuild the GNAT run-time library as documented in the
-@cite{GNAT User's Guide}
+Rebuild the GNAT run-time library as documented in
+@ref{GNAT and Libraries,,, gnat_ugn_^unw^vms^, @value{EDITION} User's
+Guide}.
 @end enumerate
 
 @unnumberedsec A.1(52): Names of Predefined Numeric Types
@@ -7411,8 +7426,9 @@
 this case a list of units can be explicitly supplied to the binder for
 inclusion in the partition (all units needed by these units will also
 be included automatically).  For full details on the use of these
-options, refer to the @cite{GNAT User's Guide} sections on Binding
-and Linking.
+options, refer to @ref{Binding Using gnatbind,,, gnat_ugn_^unw^vms^,
+@value{EDITION} User's Guide}, and @ref{Linking Using gnatlink,,,
+gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}.
 
 @sp 1
 @cartouche
@@ -13344,8 +13360,8 @@
 
 @noindent
 Provide a debugging storage pools that helps tracking memory corruption
-problems.  See section ``Finding memory problems with GNAT Debug Pool'' in
-the @cite{GNAT User's Guide}.
+problems.  @xref{The GNAT Debug Pool Facility,,, gnat_ugn_^unw^vms^,
+@value{EDITION} User's Guide}.
 
 @node GNAT.Debug_Utilities (g-debuti.ads)
 @section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
@@ -14405,10 +14421,8 @@
 The two features are similar, and both are closely related to the mechanism
 provided by the asm instruction in the GNU C compiler.  Full understanding
 and use of the facilities in this package requires understanding the asm
-instruction as described in @cite{Using the GNU Compiler Collection (GCC)}
-by Richard Stallman. The relevant section is titled ``Extensions to the C
-Language Family'' @result{} ``Assembler Instructions with C Expression
-Operands''.
+instruction, see @ref{Extended Asm,, Assembler Instructions with C Expression
+Operands, gcc, Using the GNU Compiler Collection (GCC)}.
 
 Calls to the function @code{Asm} and the procedure @code{Asm} have identical
 semantic restrictions and effects as described below.  Both are provided so
@@ -14482,7 +14496,8 @@
 optimizations with respect to the instruction specified should be
 suppressed, and that in particular, for an instruction that has outputs,
 the instruction will still be generated, even if none of the outputs are
-used.  See the full description in the GCC manual for further details.
+used.  @xref{Extended Asm,, Assembler Instructions with C Expression Operands,
+gcc, Using the GNU Compiler Collection (GCC)}, for the full description.
 Generally it is strongly advisable to use Volatile for any ASM statement
 that is missing either input or output operands, or when two or more ASM
 statements appear in sequence, to avoid unwanted optimizations. A warning
@@ -15059,7 +15074,8 @@
 Project files specify the options to be used when building a system.
 Project files can specify global settings for all tools,
 as well as tool-specific settings.
-See the chapter on project files in the GNAT Users guide for examples of use.
+@xref{Examples of Project Files,,, gnat_ugn_^unw^vms^, @value{EDITION}
+User's Guide}, for examples of use.
 
 @menu
 * Reserved Words::
Index: gcc/ada/gnat_ugn.texi
===================================================================
--- gcc/ada/gnat_ugn.texi	(Revision 133270)
+++ gcc/ada/gnat_ugn.texi	(Arbeitskopie)
@@ -923,8 +923,9 @@
 
 @itemize @bullet
 @item
-@cite{GNAT Reference Manual}, which contains all reference
-material for the GNAT implementation of Ada.
+@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, GNAT
+Reference Manual}, which contains all reference material for the GNAT
+implementation of Ada.
 
 @ifset unw
 @item
@@ -945,18 +946,19 @@
 material for the Ada 2005 programming language.
 
 @item
-@cite{Debugging with GDB}
+@xref{Top,, Debugging with GDB, gdb, Debugging with GDB},
 @ifset vms
-, located in the GNU:[DOCS] directory,
+in the GNU:[DOCS] directory,
 @end ifset
-contains all details on the use of the GNU source-level debugger.
+for all details on the use of the GNU source-level debugger.
 
 @item
-@cite{GNU Emacs Manual}
+@xref{Top,, The extensible self-documenting text editor, emacs,
+GNU Emacs Manual},
 @ifset vms
-, located in the GNU:[DOCS] directory if the EMACS kit is installed,
+located in the GNU:[DOCS] directory if the EMACS kit is installed,
 @end ifset
-contains full information on the extensible editor and programming
+for full information on the extensible editor and programming
 environment Emacs.
 
 @end itemize
@@ -2970,8 +2972,8 @@
 
 @noindent
 Interfacing at the class level can be achieved by using the GNAT specific
-pragmas such as @code{CPP_Constructor}. See the GNAT Reference Manual for
-additional information.
+pragmas such as @code{CPP_Constructor}.  @xref{Interfacing to C++,,,
+gnat_rm, GNAT Reference Manual}, for additional information.
 
 @node Linking a Mixed C++ & Ada Program
 @subsection Linking a Mixed C++ & Ada Program
@@ -3737,9 +3739,10 @@
 @cindex @option{-B} (@command{gcc})
 Load compiler executables (for example, @code{gnat1}, the Ada compiler)
 from @var{dir} instead of the default location. Only use this switch
-when multiple versions of the GNAT compiler are available. See the
-@command{gcc} manual page for further details. You would normally use the
-@option{-b} or @option{-V} switch instead.
+when multiple versions of the GNAT compiler are available.
+@xref{Directory Options,, Options for Directory Search, gcc, Using the
+GNU Compiler Collection (GCC)}, for further details. You would normally
+use the @option{-b} or @option{-V} switch instead.
 
 @item -c
 @cindex @option{-c} (@command{gcc})
@@ -3981,8 +3984,8 @@
 @cindex @option{-gnatP} (@command{gcc})
 Enable polling. This is required on some systems (notably Windows NT) to
 obtain asynchronous abort and asynchronous transfer of control capability.
-See the description of pragma Polling in the GNAT Reference Manual for
-full details.
+@xref{Pragma Polling,,, gnat_rm, GNAT Reference Manual}, for full
+details.
 
 @item -gnatq
 @cindex @option{-gnatq} (@command{gcc})
@@ -4718,8 +4721,8 @@
 The following section lists compiler switches that are available
 to control the handling of warning messages. It is also possible
 to exercise much finer control over what warnings are issued and
-suppressed using the GNAT pragma Warnings, which is documented
-in the GNAT Reference manual.
+suppressed using the GNAT pragma Warnings, @xref{Pragma Warnings,,,
+gnat_rm, GNAT Reference manual}.
 
 @table @option
 @c !sort!
@@ -7207,8 +7210,8 @@
 In addition to the language-defined hierarchies (@code{System}, @code{Ada} and
 @code{Interfaces}), the GNAT distribution provides a fourth hierarchy,
 consisting of child units of @code{GNAT}. This is a collection of generally
-useful types, subprograms, etc. See the @cite{GNAT Reference Manual} for
-further details.
+useful types, subprograms, etc. @xref{The GNAT Library, GNAT Reference Manual,,
+gnat_rm, GNAT Reference Manual}, for further details.
 
 Besides simplifying access to the RTL, a major use of search paths is
 in compiling sources from multiple directories. This can make
@@ -8459,9 +8462,10 @@
 @cindex @option{-B} (@command{gnatlink})
 Load compiler executables (for example, @code{gnat1}, the Ada compiler)
 from @var{dir} instead of the default location. Only use this switch
-when multiple versions of the GNAT compiler are available. See the
-@command{gcc} manual page for further details. You would normally use the
-@option{-b} or @option{-V} switch instead.
+when multiple versions of the GNAT compiler are available.
+@xref{Directory Options,,, gcc, The GNU Compiler Collection},
+for further details. You would normally use the @option{-b} or
+@option{-V} switch instead.
 
 @item --GCC=@var{compiler_name}
 @cindex @option{--GCC=compiler_name} (@command{gnatlink})
@@ -9500,7 +9504,8 @@
 Since the precise set of optimizations done at each level will vary from
 release to release (and sometime from target to target), it is best to think
 of the optimization settings in general terms.
-The @cite{Using GNU GCC} manual contains details about
+@xref{Optimize Options,, Options That Control Optimization, gcc, Using
+the GNU Compiler Collection (GCC)}, for details about
 ^the @option{-O} settings and a number of @option{-f} options that^how to^
 individually enable or disable specific optimizations.
 
@@ -9776,8 +9781,9 @@
 @option{-funroll-loops} and
 the various target-specific @option{-m} options (in particular, it has been
 observed that @option{-march=pentium4} can significantly improve performance
-on appropriate machines). For full details of these switches, see the
-@command{gcc} manual.
+on appropriate machines). For full details of these switches, see
+@ref{Submodel Options,, Hardware Models and Configurations, gcc, Using
+the GNU Compiler Collection (GCC)}.
 
 @node Optimization and Strict Aliasing
 @subsection Optimization and Strict Aliasing
@@ -10036,7 +10042,8 @@
 @code{Eliminate} pragmas in the GNAT configuration file @file{gnat.adc} and
 recompiling your program, you may decrease the size of its executable,
 because the compiler will not generate the code for 'eliminated' subprograms.
-See GNAT Reference Manual for more information about this pragma.
+@xref{Pragma Eliminate,,, gnat_rm, GNAT Reference Manual}, for more
+information about this pragma.
 
 @code{gnatelim} needs as its input data the name of the main subprogram
 and a bind file for a main subprogram.
@@ -10703,10 +10710,10 @@
 @noindent
 Configuration pragmas include those pragmas described as
 such in the Ada Reference Manual, as well as
-implementation-dependent pragmas that are configuration pragmas. See the
-individual descriptions of pragmas in the @cite{GNAT Reference Manual} for
-details on these additional GNAT-specific configuration pragmas. Most
-notably, the pragma @code{Source_File_Name}, which allows
+implementation-dependent pragmas that are configuration pragmas.
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
+for details on these additional GNAT-specific configuration pragmas.
+Most notably, the pragma @code{Source_File_Name}, which allows
 specifying non-default names for source files, is a configuration
 pragma. The following is a complete list of configuration pragmas
 recognized by GNAT:
@@ -11214,7 +11221,8 @@
 The next section introduces the main features of GNAT's project facility
 through a sequence of examples; subsequent sections will present the syntax
 and semantics in more detail. A more formal description of the project
-facility appears in the GNAT Reference Manual.
+facility appears in @ref{Project File Reference,,, gnat_rm, GNAT
+Reference Manual}.
 
 @c *****************************
 @c * Examples of Project Files *
@@ -18649,9 +18657,9 @@
 
 @noindent
 This chapter offers some examples of makefiles that solve specific
-problems. It does not explain how to write a makefile (see the GNU make
-documentation), nor does it try to replace the @command{gnatmake} utility
-(@pxref{The GNAT Make Program gnatmake}).
+problems. It does not explain how to write a makefile (@pxref{Top,, GNU
+make, make, GNU @code{make}}), nor does it try to replace the
+@command{gnatmake} utility (@pxref{The GNAT Make Program gnatmake}).
 
 All the examples in this section are specific to the GNU version of
 make. Although @command{make} is a standard utility, and the basic language
@@ -19962,15 +19970,15 @@
 @code{Style_Checks}. A parameter of this rule can be either @code{All_Checks},
 which enables all the style checks, or a string that has exactly the same
 structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma
-@code{Style_Checks} (for further information about this pragma, please
-refer to the @cite{@value{EDITION} Reference Manual}).
+@code{Style_Checks} (for further information about this pragma,
+@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}).
 
 @item Warnings
 To record compiler warnings (@pxref{Warning Message Control}), use the rule
 named @code{Warnings} with a parameter that is a valid
 @i{static_string_expression} argument of GNAT pragma @code{Warnings}
-(for further information about this pragma, please
-refer to the @cite{@value{EDITION} Reference Manual}).
+(for further information about this pragma, @pxref{Pragma Warnings,,,
+gnat_rm, GNAT Reference Manual}).
 
 @end table
 
@@ -20380,8 +20388,8 @@
 ON. @emph{Pragma_Name} is treated as a name of a pragma. If it
 does not correspond to any pragma name defined in the Ada
 standard or to the name of a GNAT-specific pragma defined
-in the GNAT Reference Manual, it is treated as the name of
-unknown pragma.
+in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
+Manual}, it is treated as the name of unknown pragma.
 
 @item @code{GNAT}
 All the GNAT-specific pragmas are detected; this sets
@@ -20398,10 +20406,9 @@
 checked without affecting checks for
 other pragmas. @emph{Pragma_Name} is treated as a name
 of a pragma. If it does not correspond to any pragma
-defined in the Ada standard or to any name defined in the
-GNAT Reference Manual,
-this option is treated as turning OFF detection of all
-unknown pragmas.
+defined in the Ada standard or to any name defined in
+@ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
+this option is treated as turning OFF detection of all unknown pragmas.
 
 @item GNAT
 Turn OFF detection of all GNAT-specific pragmas
@@ -21947,11 +21954,11 @@
 GNAT. The latest versions of @code{GDB} are Ada-aware and can handle
 complex Ada data structures.
 
-The manual @cite{Debugging with GDB}
+@xref{Top,, Debugging with GDB, gdb, Debugging with GDB},
 @ifset vms
-, located in the GNU:[DOCS] directory,
+located in the GNU:[DOCS] directory,
 @end ifset
-contains full details on the usage of @code{GDB}, including a section on
+for full details on the usage of @code{GDB}, including a section on
 its usage on programs. This manual should be consulted for full
 details. The section that follows is a brief introduction to the
 philosophy and use of @code{GDB}.
@@ -22031,12 +22038,12 @@
 @section Introduction to GDB Commands
 
 @noindent
-@code{GDB} contains a large repertoire of commands. The manual
-@cite{Debugging with GDB}
+@code{GDB} contains a large repertoire of commands.  @xref{Top,,
+Debugging with GDB, gdb, Debugging with GDB},
 @ifset vms
-(located in the GNU:[DOCS] directory)
+located in the GNU:[DOCS] directory,
 @end ifset
-includes extensive documentation on the use
+for extensive documentation on the use
 of these commands, together with examples of their use. Furthermore,
 the command @command{help} invoked from within GDB activates a simple help
 facility which summarizes the available commands and their options.
@@ -22131,8 +22138,8 @@
 @code{GDB} provides. Important additional capabilities, including conditional
 breakpoints, the ability to execute command sequences on a breakpoint,
 the ability to debug at the machine instruction level and many other
-features are described in detail in @cite{Debugging with GDB}.
-Note that most commands can be abbreviated
+features are described in detail in @ref{Top,, Debugging with GDB, gdb,
+Debugging with GDB}.  Note that most commands can be abbreviated
 (for example, c for continue, bt for backtrace).
 
 @node Using Ada Expressions
@@ -22165,7 +22172,8 @@
 their packages, regardless of context. Where this causes ambiguity,
 @code{GDB} asks the user's intent.
 
-For details on the supported Ada syntax, see @cite{Debugging with GDB}.
+For details on the supported Ada syntax, see @ref{Ada,, Debugging with
+GDB, gdb, Debugging with GDB}.
 
 @node Calling User-Defined Subprograms
 @section Calling User-Defined Subprograms
@@ -22325,7 +22333,7 @@
 
 @noindent
 For more detailed information on the tasking support,
-see @cite{Debugging with GDB}.
+see @ref{Top,, Debugging with GDB, gdb, Debugging with GDB}.
 
 @node Debugging Generic Units
 @section Debugging Generic Units
@@ -22984,9 +22992,9 @@
 
 For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
 attributes are recognized, although only a subset of them can sensibly
-be implemented.  The description of pragmas in the
-@cite{GNAT Reference Manual} indicates whether or not they are applicable
-to non-VMS systems.
+be implemented.  The description of pragmas in
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
+indicates whether or not they are applicable to non-VMS systems.
 
 @menu
 * Ada Language Compatibility::
@@ -23343,7 +23351,8 @@
 @noindent
 which will be accepted by GNAT (and other Ada compilers), and is also
 compatible with Ada 83. A fuller description of the restrictions
-on address specifications is found in the @cite{GNAT Reference Manual}.
+on address specifications is found in @ref{Top, GNAT Reference Manual,
+About This Guide, gnat_rm, GNAT Reference Manual}.
 
 @node Other Representation Clauses
 @subsection Other Representation Clauses
@@ -23430,8 +23439,8 @@
 
 @noindent
 The pragma @code{Extend_System} is a configuration pragma that
-is most conveniently placed in the @file{gnat.adc} file. See the
-@cite{GNAT Reference Manual} for further details.
+is most conveniently placed in the @file{gnat.adc} file. @xref{Pragma
+Extend_System,,, gnat_rm, GNAT Reference Manual} for further details.
 
 HP Ada does not allow the recompilation of the package
 @code{SYSTEM}. Instead HP Ada provides several pragmas
@@ -23462,8 +23471,8 @@
 @code{TO_ADDRESS}
 function for type @code{UNSIGNED_LONGWORD} is changed to
 @code{TO_ADDRESS_LONG}.
-See the @cite{GNAT Reference Manual} for a discussion of why this change was
-necessary.
+@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual} for a
+discussion of why this change was necessary.
 
 @noindent
 The version of @code{TO_ADDRESS} taking a @i{universal_integer} argument
@@ -23792,8 +23801,9 @@
 @end itemize
 
 @noindent
-For full details on these GNAT implementation-defined pragmas, see
-the GNAT Reference Manual.
+For full details on these GNAT implementation-defined pragmas,
+see @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
+Manual}.
 
 @menu
 * Restrictions on the Pragma INLINE::
@@ -24035,8 +24045,7 @@
 described for HP Ada or the facilities of Annex B of
 the @cite{Ada Reference Manual} (packages @code{INTERFACES.C},
 @code{INTERFACES.C.STRINGS} and @code{INTERFACES.C.POINTERS}). For more
-information, see the section ``Interfacing to C'' in the
-@cite{GNAT Reference Manual}.
+information, see @ref{Interfacing to C,,, gnat_rm, GNAT Reference Manual}.
 
 The @option{-gnatF} qualifier forces default and explicit
 @code{External_Name} parameters in pragmas @code{Import} and @code{Export}
@@ -24407,8 +24416,8 @@
 
 For further information on how GNAT interfaces to the file
 system or how I/O is implemented in programs written in
-mixed languages, see the chapter ``Implementation of the
-Standard I/O'' in the @cite{GNAT Reference Manual}.
+mixed languages, see @ref{Implementation of the Standard I/O,,,
+gnat_rm, GNAT Reference Manual}.
 This chapter covers the following:
 @itemize @bullet
 @item  Standard I/O packages
@@ -27739,8 +27748,9 @@
 @cindex pragma @code{Assert}
 on the @code{Assert} pragma that has always been available in GNAT, so this
 feature may be used with GNAT even if you are not using Ada 2005 features.
-The use of pragma @code{Assert} is described in the
-@cite{GNAT Reference Manual}, but as an example, the last test could be written:
+The use of pragma @code{Assert} is described in
+@ref{Pragma Assert,,, gnat_rm, GNAT Reference Manual}, but as an
+example, the last test could be written:
 
 @smallexample @c ada
 pragma Assert (Temperature <= 999.0, "Temperature Crazy");
@@ -28206,7 +28216,8 @@
 
 The examples in this chapter will illustrate several of the forms
 for invoking @code{Asm}; a complete specification of the syntax
-is found in the @cite{GNAT Reference Manual}.
+is found in @ref{Machine Code Insertions,,, gnat_rm, GNAT Reference
+Manual}.
 
 Under the standard GNAT conventions, the @code{Nothing} procedure
 should be in a file named @file{nothing.adb}.
@@ -29086,11 +29097,11 @@
 @noindent
 Ada compilers are allowed to supplement the language-defined pragmas, and
 these are a potential source of non-portability.  All GNAT-defined pragmas
-are described in the GNAT Reference Manual, and these include several that
-are specifically intended to correspond to other vendors' Ada 83 pragmas.
+are described in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT
+Reference Manual}, and these include several that are specifically
+intended to correspond to other vendors' Ada 83 pragmas.
 For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful.
-For
-compatibility with HP Ada 83, GNAT supplies the pragmas
+For compatibility with HP Ada 83, GNAT supplies the pragmas
 @code{Extend_System}, @code{Ident}, @code{Inline_Generic},
 @code{Interface_Name}, @code{Passive}, @code{Suppress_All},
 and @code{Volatile}.
@@ -29105,9 +29116,9 @@
 @subsection Implementation-defined attributes
 
 Analogous to pragmas, the set of attributes may be extended by an
-implementation.  All GNAT-defined attributes are described in the
-@cite{GNAT Reference Manual}, and these include several that are specifically
-intended
+implementation.  All GNAT-defined attributes are described in
+@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference
+Manual}, and these include several that are specifically intended
 to correspond to other vendors' Ada 83 attributes.  For migrating from VADS,
 the attribute @code{VADS_Size} may be useful.  For compatibility with HP
 Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and
@@ -29383,8 +29394,8 @@
 
 For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
 attributes are recognized, although only a subset of them can sensibly
-be implemented.  The description of pragmas in the
-@cite{GNAT Reference Manual}
+be implemented.  The description of pragmas in @ref{Implementation
+Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
 indicates whether or not they are applicable to non-VMS systems.
 @end ifclear
 

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Arnaud Charlet]

> OK.  In the patch below I did that.  However, for now I did not to
> rename the output file to gnat_rm_{unw,vms}.  Please say so if you want
> that, too.

No, I do not want that, and do not want such handling for gnat_rm.texi

> OK for trunk and 4.3?

Not in the proposed form I'm afraid, see below.

> gcc/ada/ChangeLog:
> 2008-03-16  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
> 
> 	PR documentation/15479
> 	* gnat_ugn.texi: Fix cross references to the GNAT Reference
> 	Manual.  Convert links to the GCC, GDB, Emacs, and GNU make
> 	manuals to be proper texinfo links.
> 	* gnat_rm.texi: Fix cross references to the GNAT User's Guide.
> 	* Make-lang.in (doc/gnat_rm.texi): New, create from
> 	ada/gnat_rm.texi using xgnatugn.

Well, I'd rather not have to preprocess gnat_rm.texi, that's a heavy
solution.

There have to be a simpler solution here, such as using a texi
variable for example.

Arno

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Ralf Wildenhues]

Hello Arno,

* Arnaud Charlet wrote on Mon, Mar 17, 2008 at 08:59:28AM CET:
> 
> Well, I'd rather not have to preprocess gnat_rm.texi, that's a heavy
> solution.

> There have to be a simpler solution here, such as using a texi
> variable for example.

That's what I thought as well at first, and I've tried it, too:

>>>> [...] because texinfo doesn't like @value's in the info-file-name
>>>> argument of cross-references.[1]
[...]
>>>> [1] I've reported that bug to bug-texinfo, along with the bug that
>>>>     prevents clickable inter-PDF links when the info-file-name contains
>>>>     an underscore.

FWIW, here's the bug report I mentioned:
<http://lists.gnu.org/archive/html/bug-texinfo/2008-03/msg00033.html>.

Chances are low, but I may look into fixing that bug if Karl won't,
but anyway it will require an updated makeinfo (unlike the click bug),
which rules out that GCC can rely on it for the next couple of years.

So the only other thing I can come up with is something like

| language version.  (Please refer to
| @ifset unw
| @ref{Compiling Different Versions of Ada,,, gnat_ugn_unw, @value{EDITION}
| User's Guide},
| @end ifset
| @ifset vms
| @ref{Compiling Different Versions of Ada,,, gnat_ugn_vms, @value{EDITION}
| User's Guide},
| @end ifset
| for details on

which strikes me as uglier and more error-prone than:

| language version.  (Please refer to @ref{Compiling Different Versions of
| Ada,,, gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}, for details on

Do you know a better way?  Otherwise, ok for 4.4 and 4.3?

Thanks,
Ralf

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Arnaud Charlet]

> which strikes me as uglier and more error-prone than:

It's indeed ugly as well.

> | language version.  (Please refer to @ref{Compiling Different Versions of
> | Ada,,, gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}, for details on
> 
> Do you know a better way?

Yes, I do: instead, we can modify the makefile to generate/rename the gnat_ugn
to always the same name: gnat_ugn.info (or gnat_ugn.html, ...), so that
there is no need to conditionalize references to this document in gnat_rm.texi

> Otherwise, ok for 4.4 and 4.3?

No, it's still not OK in the current form. Sorry about that, but the change
as proposed would be a real pain to maintain, which is what matters over what's
possible as a one time change.

Arno

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Ralf Wildenhues]

* Arnaud Charlet wrote on Tue, Mar 18, 2008 at 08:53:30AM CET:
> 
> > | language version.  (Please refer to @ref{Compiling Different Versions of
> > | Ada,,, gnat_ugn_^unw^vms^, @value{EDITION} User's Guide}, for details on
> > 
> > Do you know a better way?
> 
> Yes, I do: instead, we can modify the makefile to generate/rename the gnat_ugn
> to always the same name: gnat_ugn.info (or gnat_ugn.html, ...), so that
> there is no need to conditionalize references to this document in gnat_rm.texi

OK.  This still leaves a few questions open:

Should it still be possible to build the VMS version of the User's Guide
as well as the UNW version using xgnatugn, but both should now have the
same name?  Or should just the UNW version be renamed to gnat_ugn.info?
Should it still be possible with xgnatugn to generate an UNW version
with the gnat_ugn_unw name?

Asking here because I assume that there is some build process external
to GCC which generates the VMS version (the code in gcc/ada/Make-lang.in
doesn't do this now) and maybe wants to have a parallel installation of
the User's Guides for different systems.  It would really help if you
could point me to such an external build process if any, because
otherwise I am back to guessing about what is desired without knowing
the side conditions.

I assume maintainer-scripts/update_web_docs_svn should be adjusted to
generate gnat_ugn only, and install that, right?  Also I assume that
this change will make this patch less suitable for the 4.3 branch?

Thanks,
Ralf

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Arnaud Charlet]

> Should it still be possible to build the VMS version of the User's Guide
> as well as the UNW version using xgnatugn,

Yes. But both will never end up under the same directory, so they can end
up with the same name.

> but both should now have the
> same name?  Or should just the UNW version be renamed to gnat_ugn.info?
> Should it still be possible with xgnatugn to generate an UNW version
> with the gnat_ugn_unw name?

Preferably, yes. In other words, if you could keep xgnatugn as it is today,
that'd be easier to handle.

> Asking here because I assume that there is some build process external
> to GCC which generates the VMS version (the code in gcc/ada/Make-lang.in

Indeed, for the FSF version, currently only the unw version is generated,
although I guess in theory, we could generate the other (when doing
a VMS build, which probably nobody outside AdaCore does these days).

Let me know if you have further questions.

Arno

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Ralf Wildenhues]

* Arnaud Charlet wrote on Tue, Mar 18, 2008 at 11:02:20PM CET:
> > Should it still be possible to build the VMS version of the User's Guide
> > as well as the UNW version using xgnatugn,
> 
> Yes. But both will never end up under the same directory, so they can end
> up with the same name.

OK, but ...

> > but both should now have the
> > same name?  Or should just the UNW version be renamed to gnat_ugn.info?
> > Should it still be possible with xgnatugn to generate an UNW version
> > with the gnat_ugn_unw name?
> 
> Preferably, yes.

... this requires that we need at least one other substitution (the
@setfilename must be choosable as gnat_ugn or gnat_ugn_unw for the UNW
version), which kind of contradicts with this requirement:

> In other words, if you could keep xgnatugn as it is today,
> that'd be easier to handle.

Cheers,
Ralf

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Arnaud Charlet]

> > > but both should now have the
> > > same name?  Or should just the UNW version be renamed to gnat_ugn.info?
> > > Should it still be possible with xgnatugn to generate an UNW version
> > > with the gnat_ugn_unw name?
> > 
> > Preferably, yes.
> 
> ... this requires that we need at least one other substitution (the
> @setfilename must be choosable as gnat_ugn or gnat_ugn_unw for the UNW
> version), which kind of contradicts with this requirement:
> 
> > In other words, if you could keep xgnatugn as it is today,
> > that'd be easier to handle.

Well, I see where the discrepency is.

xgnatugn generates gnat_ugn_xxx.texi, while you're talking about the .info
generated file. So we were talking about two different things.

It is fine and actually desirable to remove the setfilename instructions
in gnat_ugn.texi to generate a filename other than gnat_ugn.info. This is
actually what we do at AdaCore.

In other words, it's fine to require that gnat_ugn*.texi will always
generate a gnat_ugn.info.

Arno

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Ralf Wildenhues]

* Arnaud Charlet wrote on Wed, Mar 19, 2008 at 08:47:17AM CET:
> 
> xgnatugn generates gnat_ugn_xxx.texi, while you're talking about the .info
> generated file. So we were talking about two different things.

Well, maybe, but the filename needs to be embedded (with @setfilename)
in the input file of makeinfo already, so they really are related.

> It is fine and actually desirable to remove the setfilename instructions
> in gnat_ugn.texi to generate a filename other than gnat_ugn.info. This is
> actually what we do at AdaCore.
> 
> In other words, it's fine to require that gnat_ugn*.texi will always
> generate a gnat_ugn.info.

Alright.  I think the patch below does what you want.

Tested 'make info pdf dvi'.  OK for trunk?  What about 4.3?

Thanks,
Ralf

gcc/ada/ChangeLog:
2008-03-20  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>

	PR documentation/15479
	* Make-lang.in (doc/gnat_ugn.texi) Renamed from ...
	(doc/gnat_ugn_unw.texi): ... this, and adjusted.
	(doc/gnat_ugn.info): Renamed from ...
	(doc/gnat_ugn_unw.info): ... this.
	(doc/gnat_ugn.dvi): Renamed from ...
	(doc/gnat_ugn_unw.dvi): ... this.
	(doc/gnat_ugn.pdf): Renamed from ...
	(doc/gnat_ugn_unw.pdf): ... this.
	(ADA_INFOFILES, ADA_PDFFILES, ada.install-info, ada.dvi):
	Adjusted.
	* gnat_ugn.texi (FILE): Hard-code gnat_ugn; set filename
	unconditionally to gnat_ugn.info.  Fix cross references to the
	GNAT Reference Manual.  Convert links to the GCC, GDB, Emacs,
	and GNU make manuals to be proper texinfo links.
	* gnat_rm.texi: Fix cross references to the GNAT User's Guide.

diff --git a/gcc/ada/Make-lang.in b/gcc/ada/Make-lang.in
index 4e6d3f2..dfc1493 100644
--- a/gcc/ada/Make-lang.in
+++ b/gcc/ada/Make-lang.in
@@ -394,16 +394,16 @@ ada/doctools/xgnatugn$(build_exeext): ada/xgnatugn.adb
 	$(CP) $^ ada/doctools
 	cd ada/doctools && $(GNATMAKE) -q xgnatugn
 
-# Note that gnat_ugn_unw.texi does not depend on xgnatugn 
-# being built so we can distribute a pregenerated gnat_ugn_unw.info
+# Note that doc/gnat_ugn.texi does not depend on xgnatugn
+# being built so we can distribute a pregenerated doc/gnat_ugn.info
 
-doc/gnat_ugn_unw.texi: $(srcdir)/ada/gnat_ugn.texi $(srcdir)/ada/ug_words \
+doc/gnat_ugn.texi: $(srcdir)/ada/gnat_ugn.texi $(srcdir)/ada/ug_words \
    $(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
 	$(MAKE) ada/doctools/xgnatugn$(build_exeext)
 	ada/doctools/xgnatugn unw $(srcdir)/ada/gnat_ugn.texi \
-	   $(srcdir)/ada/ug_words doc/gnat_ugn_unw.texi
+	   $(srcdir)/ada/ug_words doc/gnat_ugn.texi
 
-doc/gnat_ugn_unw.info: doc/gnat_ugn_unw.texi			\
+doc/gnat_ugn.info: doc/gnat_ugn.texi			\
    $(gcc_docdir)/include/fdl.texi $(gcc_docdir)/include/gcc-common.texi	\
    gcc-vers.texi
 	if [ x$(BUILD_INFO) = xinfo ]; then \
@@ -428,7 +428,7 @@ doc/gnat-style.info: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi	\
             -I$(srcdir)/ada -o $@ $<; \
 	else true; fi
 
-ADA_INFOFILES = doc/gnat_ugn_unw.info doc/gnat_ugn_unw.texi \
+ADA_INFOFILES = doc/gnat_ugn.info doc/gnat_ugn.texi \
                 doc/gnat_rm.info doc/gnat-style.info
 
 ada.info: $(ADA_INFOFILES)
@@ -436,14 +436,14 @@ ada.info: $(ADA_INFOFILES)
 ada.srcinfo: $(ADA_INFOFILES)
 	-$(CP) $^ $(srcdir)/doc
 
-ada.install-info: $(DESTDIR)$(infodir)/gnat_ugn_unw.info \
+ada.install-info: $(DESTDIR)$(infodir)/gnat_ugn.info \
 	$(DESTDIR)$(infodir)/gnat_rm.info \
 	$(DESTDIR)$(infodir)/gnat-style.info
 
-ada.dvi: doc/gnat_ugn_unw.dvi \
+ada.dvi: doc/gnat_ugn.dvi \
       doc/gnat_rm.dvi doc/gnat-style.dvi
 
-ADA_PDFFILES = doc/gnat_ugn_unw.pdf \
+ADA_PDFFILES = doc/gnat_ugn.pdf \
                doc/gnat_rm.pdf doc/gnat-style.pdf
 
 ada.pdf: $(ADA_PDFFILES)
@@ -460,7 +460,7 @@ ada.install-pdf: $(ADA_PDFFILES)
 
 ada.html:
 
-doc/gnat_ugn_unw.dvi: doc/gnat_ugn_unw.texi $(gcc_docdir)/include/fdl.texi	\
+doc/gnat_ugn.dvi: doc/gnat_ugn.texi $(gcc_docdir)/include/fdl.texi	\
 	$(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
 	$(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $<
 
@@ -471,7 +471,7 @@ doc/gnat_rm.dvi: ada/gnat_rm.texi $(gcc_docdir)/include/fdl.texi	\
 doc/gnat-style.dvi: ada/gnat-style.texi $(gcc_docdir)/include/fdl.texi
 	$(TEXI2DVI) -c -I $(abs_docdir)/include -o $@ $<
 
-doc/gnat_ugn_unw.pdf: doc/gnat_ugn_unw.texi $(gcc_docdir)/include/fdl.texi	\
+doc/gnat_ugn.pdf: doc/gnat_ugn.texi $(gcc_docdir)/include/fdl.texi	\
 	$(gcc_docdir)/include/gcc-common.texi gcc-vers.texi
 	$(TEXI2PDF) -c -I $(abs_docdir)/include -o $@ $<
 
diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index 0dcc1a3..84564ac 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -462,8 +462,8 @@ Ada 83 compatibility mode.
 By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION},
 but you can override with a compiler switch
 to explicitly specify the language version.
-(Please refer to the section ``Compiling Different Versions of Ada'', in
-@cite{@value{EDITION} User's Guide}, for details on these switches.)
+(Please refer to @ref{Compiling Different Versions of Ada,,, gnat_ugn,
+@value{EDITION} User's Guide}, for details on these switches.)
 Throughout this manual, references to ``Ada'' without a year suffix
 apply to both the Ada 95 and Ada 2005 versions of the language.
 
@@ -630,8 +630,9 @@ See the following documents for further information on GNAT:
 
 @itemize @bullet
 @item
-@cite{GNAT User's Guide}, which provides information on how to use
-the GNAT compiler system.
+@xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn,
+@value{EDITION} User's Guide}, which provides information on how to use the
+GNAT compiler system.
 
 @item
 @cite{Ada 95 Reference Manual}, which contains all reference
@@ -1524,8 +1525,8 @@ the @option{-gnatE} switch had been specified on the command
 line.  If the parameter is @code{Static}, then the default GNAT static
 model is used.  This configuration pragma overrides the setting
 of the command line.  For full details on the elaboration models
-used by the GNAT compiler, see section ``Elaboration Order
-Handling in GNAT'' in the @cite{GNAT User's Guide}.
+used by the GNAT compiler, see @ref{Elaboration Order Handling in GNAT,,,
+gnat_ugn, @value{EDITION} User's Guide}.
 
 @node Pragma Eliminate
 @unnumberedsec Pragma Eliminate
@@ -1980,7 +1981,8 @@ you can construct your own extension unit following the above
 definition.  Note that such a package is a child of @code{System}
 and thus is considered part of the implementation.  To compile
 it you will have to use the appropriate switch for compiling
-system units.  See the GNAT User's Guide for details.
+system units.  @xref{Top, @value{EDITION} User's Guide, About This
+Guide,, gnat_ugn, @value{EDITION} User's Guide}, for details.
 
 @node Pragma External
 @unnumberedsec Pragma External
@@ -2170,9 +2172,9 @@ floating point types declared in the packages @code{Standard} and
 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
 argument may be @code{VAX_Float} to specify the use of the VAX float
 format for the floating-point types in Standard. This requires that
-the standard runtime libraries be recompiled. See the
-description of the @code{GNAT LIBRARY} command in the OpenVMS version
-of the GNAT Users Guide for details on the use of this command.
+the standard runtime libraries be recompiled.  @xref{The GNAT Run-Time
+Library Builder gnatlbr,,, gnat_ugn, @value{EDITION} User's Guide
+OpenVMS}, for a description of the @code{GNAT LIBRARY} command.
 
 The two argument form specifies the representation to be used for
 the specified floating-point type. On all systems other than OpenVMS,
@@ -3059,9 +3061,10 @@ type @code{Long_Float} and for floating point type representations with
 @code{digits} specified in the range 7 through 15.
 For further details on this pragma, see the
 @cite{DEC Ada Language Reference Manual}, section 3.5.7b.  Note that to use
-this pragma, the standard runtime libraries must be recompiled.  See the
-description of the @code{GNAT LIBRARY} command in the OpenVMS version
-of the GNAT User's Guide for details on the use of this command.
+this pragma, the standard runtime libraries must be recompiled.
+@xref{The GNAT Run-Time Library Builder gnatlbr,,, gnat_ugn,
+@value{EDITION} User's Guide OpenVMS}, for a description of the
+@code{GNAT LIBRARY} command.
 
 @node Pragma Machine_Attribute
 @unnumberedsec Pragma Machine_Attribute
@@ -3085,8 +3088,10 @@ in GNU C, where @code{@var{attribute_name}} is recognized by the
 target macro @code{TARGET_ATTRIBUTE_TABLE} which is defined for each
 machine.  The optional parameter @var{info} is transformed into an
 identifier, which may make this pragma unusable for some attributes
-(parameter of some attributes must be a number or a string). See the
-GCC manual for further information.  It is not possible to specify
+(parameter of some attributes must be a number or a string).
+@xref{Target Attributes,, Defining target-specific uses of
+@code{__attribute__}, gccint, GNU Compiler Colletion (GCC) Internals},
+further information.  It is not possible to specify
 attributes defined by other languages, only attributes defined by the
 machine the code is intended to run on.
 
@@ -3198,8 +3203,8 @@ strict aliasing optimization for the given type.  The form with no
 arguments is a configuration pragma which applies to all access types
 declared in units to which the pragma applies. For a detailed
 description of the strict aliasing optimization, and the situations
-in which it must be suppressed, see section
-``Optimization and Strict Aliasing'' in the @value{EDITION} User's Guide.
+in which it must be suppressed, see @ref{Optimization and Strict
+Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
 
 @node Pragma Normalize_Scalars
 @unnumberedsec Pragma Normalize_Scalars
@@ -3459,8 +3464,9 @@ targets that do not normally support the capability.  The version of
 @code{Poll} in this file makes a call to the appropriate runtime routine
 to test for an abort condition.
 
-Note that polling can also be enabled by use of the @option{-gnatP} switch.  See
-the @cite{GNAT User's Guide} for details.
+Note that polling can also be enabled by use of the @option{-gnatP} switch.
+@xref{Switches for gcc,,, gnat_ugn, @value{EDITION} User's Guide}, for
+details.
 
 @node Pragma Profile (Ravenscar)
 @unnumberedsec Pragma Profile (Ravenscar)
@@ -3802,8 +3808,9 @@ A pragma Source_File_Name cannot appear after a
 @ref{Pragma Source_File_Name_Project}.
 
 For more details on the use of the @code{Source_File_Name} pragma,
-see the sections ``Using Other File Names'' and
-``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}.
+@xref{Using Other File Names,,, gnat_ugn, @value{EDITION} User's Guide},
+and @ref{Alternative File Naming Schemes,,, gnat_ugn, @value{EDITION}
+User's Guide}.
 
 @node Pragma Source_File_Name_Project
 @unnumberedsec Pragma Source_File_Name_Project
@@ -3961,8 +3968,9 @@ gcc -c -gnatyl @dots{}
 
 @noindent
 The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the @code{gnaty} switch with no options.  See GNAT User's
-Guide for details.
+to the use of the @code{gnaty} switch with no options.  @xref{Top,
+@value{EDITION} User's Guide, About This Guide, gnat_ugn,
+@value{EDITION} User's Guide}, for details.
 
 The forms with @code{Off} and @code{On}
 can be used to temporarily disable style checks
@@ -4278,8 +4286,8 @@ declarative part.  The effect is to inhibit strict type-based aliasing
 optimization for the given type.  In other words, the effect is as though
 access types designating this type were subject to pragma No_Strict_Aliasing.
 For a detailed description of the strict aliasing optimization, and the
-situations in which it must be suppressed, see section
-``Optimization and Strict Aliasing'' in the @value{EDITION} User's Guide.
+situations in which it must be suppressed, @xref{Optimization and Strict
+Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
 
 @node Pragma Universal_Data
 @unnumberedsec Pragma Universal_Data
@@ -4566,7 +4574,8 @@ control over which warnings are active. The string is a list of letters
 specifying which warnings are to be activated and which deactivated. The
 code for these letters is the same as the string used in the command
 line switch controlling warnings. The following is a brief summary. For
-full details see the GNAT Users Guide:
+full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION}
+User's Guide}.
 
 @smallexample
 a   turn on all optional warnings (except d,h,l)
@@ -6383,8 +6392,8 @@ $ mv s-strxdr.adb s-stratt.adb
 @end smallexample
 
 @item
-Rebuild the GNAT run-time library as documented in the
-@cite{GNAT User's Guide}
+Rebuild the GNAT run-time library as documented in
+@ref{GNAT and Libraries,,, gnat_ugn, @value{EDITION} User's Guide}.
 @end enumerate
 
 @unnumberedsec A.1(52): Names of Predefined Numeric Types
@@ -7411,8 +7420,8 @@ provides the binder options @option{-z} and @option{-n} respectively, and in
 this case a list of units can be explicitly supplied to the binder for
 inclusion in the partition (all units needed by these units will also
 be included automatically).  For full details on the use of these
-options, refer to the @cite{GNAT User's Guide} sections on Binding
-and Linking.
+options, refer to @ref{The GNAT Make Program gnatmake,,, gnat_ugn,
+@value{EDITION} User's Guide}.
 
 @sp 1
 @cartouche
@@ -13344,8 +13353,8 @@ obtaining information about exceptions provided by Ada 83 compilers.
 
 @noindent
 Provide a debugging storage pools that helps tracking memory corruption
-problems.  See section ``Finding memory problems with GNAT Debug Pool'' in
-the @cite{GNAT User's Guide}.
+problems.  @xref{The GNAT Debug Pool Facility,,, gnat_ugn,
+@value{EDITION} User's Guide}.
 
 @node GNAT.Debug_Utilities (g-debuti.ads)
 @section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
@@ -14405,10 +14414,8 @@ including machine instructions in a subprogram.
 The two features are similar, and both are closely related to the mechanism
 provided by the asm instruction in the GNU C compiler.  Full understanding
 and use of the facilities in this package requires understanding the asm
-instruction as described in @cite{Using the GNU Compiler Collection (GCC)}
-by Richard Stallman. The relevant section is titled ``Extensions to the C
-Language Family'' @result{} ``Assembler Instructions with C Expression
-Operands''.
+instruction, see @ref{Extended Asm,, Assembler Instructions with C Expression
+Operands, gcc, Using the GNU Compiler Collection (GCC)}.
 
 Calls to the function @code{Asm} and the procedure @code{Asm} have identical
 semantic restrictions and effects as described below.  Both are provided so
@@ -14482,7 +14489,8 @@ the literal value @code{True} to indicate to the code generator that all
 optimizations with respect to the instruction specified should be
 suppressed, and that in particular, for an instruction that has outputs,
 the instruction will still be generated, even if none of the outputs are
-used.  See the full description in the GCC manual for further details.
+used.  @xref{Extended Asm,, Assembler Instructions with C Expression Operands,
+gcc, Using the GNU Compiler Collection (GCC)}, for the full description.
 Generally it is strongly advisable to use Volatile for any ASM statement
 that is missing either input or output operands, or when two or more ASM
 statements appear in sequence, to avoid unwanted optimizations. A warning
@@ -15059,7 +15067,8 @@ This chapter describes the syntax and semantics of project files.
 Project files specify the options to be used when building a system.
 Project files can specify global settings for all tools,
 as well as tool-specific settings.
-See the chapter on project files in the GNAT Users guide for examples of use.
+@xref{Examples of Project Files,,, gnat_ugn, @value{EDITION} User's Guide},
+for examples of use.
 
 @menu
 * Reserved Words::
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 7b4ccfe..daa7fcd 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -89,19 +89,14 @@
 @set EDITION GNAT
 @set DEFAULTLANGUAGEVERSION Ada 2005
 @set NONDEFAULTLANGUAGEVERSION Ada 95
-
-@ifset unw
-@setfilename gnat_ugn_unw.info
-@end ifset
+@set FILE gnat_ugn
 
 @ifset unw
 @set PLATFORM
-@set FILE gnat_ugn_unw
 @end ifset
 
 @ifset vms
 @set PLATFORM OpenVMS
-@set FILE gnat_ugn_vms
 @end ifset
 
 @settitle @value{EDITION} User's Guide @value{PLATFORM}
@@ -923,8 +918,9 @@ documents:
 
 @itemize @bullet
 @item
-@cite{GNAT Reference Manual}, which contains all reference
-material for the GNAT implementation of Ada.
+@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, GNAT
+Reference Manual}, which contains all reference material for the GNAT
+implementation of Ada.
 
 @ifset unw
 @item
@@ -945,18 +941,19 @@ material for the Ada 95 programming language.
 material for the Ada 2005 programming language.
 
 @item
-@cite{Debugging with GDB}
+@xref{Top,, Debugging with GDB, gdb, Debugging with GDB},
 @ifset vms
-, located in the GNU:[DOCS] directory,
+in the GNU:[DOCS] directory,
 @end ifset
-contains all details on the use of the GNU source-level debugger.
+for all details on the use of the GNU source-level debugger.
 
 @item
-@cite{GNU Emacs Manual}
+@xref{Top,, The extensible self-documenting text editor, emacs,
+GNU Emacs Manual},
 @ifset vms
-, located in the GNU:[DOCS] directory if the EMACS kit is installed,
+located in the GNU:[DOCS] directory if the EMACS kit is installed,
 @end ifset
-contains full information on the extensible editor and programming
+for full information on the extensible editor and programming
 environment Emacs.
 
 @end itemize
@@ -2970,8 +2967,8 @@ the pragma import.
 
 @noindent
 Interfacing at the class level can be achieved by using the GNAT specific
-pragmas such as @code{CPP_Constructor}. See the GNAT Reference Manual for
-additional information.
+pragmas such as @code{CPP_Constructor}.  @xref{Interfacing to C++,,,
+gnat_rm, GNAT Reference Manual}, for additional information.
 
 @node Linking a Mixed C++ & Ada Program
 @subsection Linking a Mixed C++ & Ada Program
@@ -3737,9 +3734,10 @@ system configuration. You must have a GNAT cross-compiler built if
 @cindex @option{-B} (@command{gcc})
 Load compiler executables (for example, @code{gnat1}, the Ada compiler)
 from @var{dir} instead of the default location. Only use this switch
-when multiple versions of the GNAT compiler are available. See the
-@command{gcc} manual page for further details. You would normally use the
-@option{-b} or @option{-V} switch instead.
+when multiple versions of the GNAT compiler are available.
+@xref{Directory Options,, Options for Directory Search, gcc, Using the
+GNU Compiler Collection (GCC)}, for further details. You would normally
+use the @option{-b} or @option{-V} switch instead.
 
 @item -c
 @cindex @option{-c} (@command{gcc})
@@ -3981,8 +3979,8 @@ Suppress all checks.
 @cindex @option{-gnatP} (@command{gcc})
 Enable polling. This is required on some systems (notably Windows NT) to
 obtain asynchronous abort and asynchronous transfer of control capability.
-See the description of pragma Polling in the GNAT Reference Manual for
-full details.
+@xref{Pragma Polling,,, gnat_rm, GNAT Reference Manual}, for full
+details.
 
 @item -gnatq
 @cindex @option{-gnatq} (@command{gcc})
@@ -4718,8 +4716,8 @@ A range in a @code{for} loop that is known to be null or might be null
 The following section lists compiler switches that are available
 to control the handling of warning messages. It is also possible
 to exercise much finer control over what warnings are issued and
-suppressed using the GNAT pragma Warnings, which is documented
-in the GNAT Reference manual.
+suppressed using the GNAT pragma Warnings, @xref{Pragma Warnings,,,
+gnat_rm, GNAT Reference manual}.
 
 @table @option
 @c !sort!
@@ -7207,8 +7205,8 @@ the built-in defaults cause these files to be found.
 In addition to the language-defined hierarchies (@code{System}, @code{Ada} and
 @code{Interfaces}), the GNAT distribution provides a fourth hierarchy,
 consisting of child units of @code{GNAT}. This is a collection of generally
-useful types, subprograms, etc. See the @cite{GNAT Reference Manual} for
-further details.
+useful types, subprograms, etc. @xref{Top, GNAT Reference Manual, About
+This Guid, gnat_rm, GNAT Reference Manual}, for further details.
 
 Besides simplifying access to the RTL, a major use of search paths is
 in compiling sources from multiple directories. This can make
@@ -8459,9 +8457,10 @@ system configuration. You must have a GNAT cross-compiler built if
 @cindex @option{-B} (@command{gnatlink})
 Load compiler executables (for example, @code{gnat1}, the Ada compiler)
 from @var{dir} instead of the default location. Only use this switch
-when multiple versions of the GNAT compiler are available. See the
-@command{gcc} manual page for further details. You would normally use the
-@option{-b} or @option{-V} switch instead.
+when multiple versions of the GNAT compiler are available.
+@xref{Directory Options,,, gcc, The GNU Compiler Collection},
+for further details. You would normally use the @option{-b} or
+@option{-V} switch instead.
 
 @item --GCC=@var{compiler_name}
 @cindex @option{--GCC=compiler_name} (@command{gnatlink})
@@ -9500,7 +9499,8 @@ and a time optimization on the same compile command.
 Since the precise set of optimizations done at each level will vary from
 release to release (and sometime from target to target), it is best to think
 of the optimization settings in general terms.
-The @cite{Using GNU GCC} manual contains details about
+@xref{Optimize Options,, Options That Control Optimization, gcc, Using
+the GNU Compiler Collection (GCC)}, for details about
 ^the @option{-O} settings and a number of @option{-f} options that^how to^
 individually enable or disable specific optimizations.
 
@@ -9776,8 +9776,9 @@ to work. Examples of switches in this category are
 @option{-funroll-loops} and
 the various target-specific @option{-m} options (in particular, it has been
 observed that @option{-march=pentium4} can significantly improve performance
-on appropriate machines). For full details of these switches, see the
-@command{gcc} manual.
+on appropriate machines). For full details of these switches, see
+@ref{Submodel Options,, Hardware Models and Configurations, gcc, Using
+the GNU Compiler Collection (GCC)}.
 
 @node Optimization and Strict Aliasing
 @subsection Optimization and Strict Aliasing
@@ -10036,7 +10037,8 @@ subprograms that are declared but never called. By placing the list of
 @code{Eliminate} pragmas in the GNAT configuration file @file{gnat.adc} and
 recompiling your program, you may decrease the size of its executable,
 because the compiler will not generate the code for 'eliminated' subprograms.
-See GNAT Reference Manual for more information about this pragma.
+@xref{Pragma Eliminate,,, gnat_rm, GNAT Reference Manual}, for more
+information about this pragma.
 
 @code{gnatelim} needs as its input data the name of the main subprogram
 and a bind file for a main subprogram.
@@ -10703,10 +10705,10 @@ unit will be skipped.
 @noindent
 Configuration pragmas include those pragmas described as
 such in the Ada Reference Manual, as well as
-implementation-dependent pragmas that are configuration pragmas. See the
-individual descriptions of pragmas in the @cite{GNAT Reference Manual} for
-details on these additional GNAT-specific configuration pragmas. Most
-notably, the pragma @code{Source_File_Name}, which allows
+implementation-dependent pragmas that are configuration pragmas.
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
+for details on these additional GNAT-specific configuration pragmas.
+Most notably, the pragma @code{Source_File_Name}, which allows
 specifying non-default names for source files, is a configuration
 pragma. The following is a complete list of configuration pragmas
 recognized by GNAT:
@@ -11214,7 +11216,8 @@ that might be used by the developers.
 The next section introduces the main features of GNAT's project facility
 through a sequence of examples; subsequent sections will present the syntax
 and semantics in more detail. A more formal description of the project
-facility appears in the GNAT Reference Manual.
+facility appears in @ref{Project File Reference,,, gnat_rm, GNAT
+Reference Manual}.
 
 @c *****************************
 @c * Examples of Project Files *
@@ -18649,9 +18652,9 @@ to use it.
 
 @noindent
 This chapter offers some examples of makefiles that solve specific
-problems. It does not explain how to write a makefile (see the GNU make
-documentation), nor does it try to replace the @command{gnatmake} utility
-(@pxref{The GNAT Make Program gnatmake}).
+problems. It does not explain how to write a makefile (@pxref{Top,, GNU
+make, make, GNU @code{make}}), nor does it try to replace the
+@command{gnatmake} utility (@pxref{The GNAT Make Program gnatmake}).
 
 All the examples in this section are specific to the GNU version of
 make. Although @command{make} is a standard utility, and the basic language
@@ -19962,15 +19965,15 @@ To record compiler style checks, use the rule named
 @code{Style_Checks}. A parameter of this rule can be either @code{All_Checks},
 which enables all the style checks, or a string that has exactly the same
 structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma
-@code{Style_Checks} (for further information about this pragma, please
-refer to the @cite{@value{EDITION} Reference Manual}).
+@code{Style_Checks} (for further information about this pragma,
+@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}).
 
 @item Warnings
 To record compiler warnings (@pxref{Warning Message Control}), use the rule
 named @code{Warnings} with a parameter that is a valid
 @i{static_string_expression} argument of GNAT pragma @code{Warnings}
-(for further information about this pragma, please
-refer to the @cite{@value{EDITION} Reference Manual}).
+(for further information about this pragma, @pxref{Pragma Warnings,,,
+gnat_rm, GNAT Reference Manual}).
 
 @end table
 
@@ -20380,8 +20383,8 @@ checked and sets the checks for all the specified pragmas
 ON. @emph{Pragma_Name} is treated as a name of a pragma. If it
 does not correspond to any pragma name defined in the Ada
 standard or to the name of a GNAT-specific pragma defined
-in the GNAT Reference Manual, it is treated as the name of
-unknown pragma.
+in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
+Manual}, it is treated as the name of unknown pragma.
 
 @item @code{GNAT}
 All the GNAT-specific pragmas are detected; this sets
@@ -20398,10 +20401,9 @@ Removes the specified pragma from the set of pragmas to be
 checked without affecting checks for
 other pragmas. @emph{Pragma_Name} is treated as a name
 of a pragma. If it does not correspond to any pragma
-defined in the Ada standard or to any name defined in the
-GNAT Reference Manual,
-this option is treated as turning OFF detection of all
-unknown pragmas.
+defined in the Ada standard or to any name defined in
+@ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
+this option is treated as turning OFF detection of all unknown pragmas.
 
 @item GNAT
 Turn OFF detection of all GNAT-specific pragmas
@@ -21947,11 +21949,11 @@ and in particular is capable of debugging Ada programs compiled with
 GNAT. The latest versions of @code{GDB} are Ada-aware and can handle
 complex Ada data structures.
 
-The manual @cite{Debugging with GDB}
+@xref{Top,, Debugging with GDB, gdb, Debugging with GDB},
 @ifset vms
-, located in the GNU:[DOCS] directory,
+located in the GNU:[DOCS] directory,
 @end ifset
-contains full details on the usage of @code{GDB}, including a section on
+for full details on the usage of @code{GDB}, including a section on
 its usage on programs. This manual should be consulted for full
 details. The section that follows is a brief introduction to the
 philosophy and use of @code{GDB}.
@@ -22031,12 +22033,12 @@ describes some of the additional commands that can be given to @code{GDB}.
 @section Introduction to GDB Commands
 
 @noindent
-@code{GDB} contains a large repertoire of commands. The manual
-@cite{Debugging with GDB}
+@code{GDB} contains a large repertoire of commands.  @xref{Top,,
+Debugging with GDB, gdb, Debugging with GDB},
 @ifset vms
-(located in the GNU:[DOCS] directory)
+located in the GNU:[DOCS] directory,
 @end ifset
-includes extensive documentation on the use
+for extensive documentation on the use
 of these commands, together with examples of their use. Furthermore,
 the command @command{help} invoked from within GDB activates a simple help
 facility which summarizes the available commands and their options.
@@ -22131,8 +22133,8 @@ The above list is a very short introduction to the commands that
 @code{GDB} provides. Important additional capabilities, including conditional
 breakpoints, the ability to execute command sequences on a breakpoint,
 the ability to debug at the machine instruction level and many other
-features are described in detail in @cite{Debugging with GDB}.
-Note that most commands can be abbreviated
+features are described in detail in @ref{Top,, Debugging with GDB, gdb,
+Debugging with GDB}.  Note that most commands can be abbreviated
 (for example, c for continue, bt for backtrace).
 
 @node Using Ada Expressions
@@ -22165,7 +22167,8 @@ packages, thus making it unnecessary to fully qualify most names with
 their packages, regardless of context. Where this causes ambiguity,
 @code{GDB} asks the user's intent.
 
-For details on the supported Ada syntax, see @cite{Debugging with GDB}.
+For details on the supported Ada syntax, see @ref{Top,, Debugging with
+GDB, gdb, Debugging with GDB}.
 
 @node Calling User-Defined Subprograms
 @section Calling User-Defined Subprograms
@@ -22325,7 +22328,7 @@ perturbed.
 
 @noindent
 For more detailed information on the tasking support,
-see @cite{Debugging with GDB}.
+see @ref{Top,, Debugging with GDB, gdb, Debugging with GDB}.
 
 @node Debugging Generic Units
 @section Debugging Generic Units
@@ -22984,9 +22987,9 @@ GNAT always follows the Alpha implementation.
 
 For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
 attributes are recognized, although only a subset of them can sensibly
-be implemented.  The description of pragmas in the
-@cite{GNAT Reference Manual} indicates whether or not they are applicable
-to non-VMS systems.
+be implemented.  The description of pragmas in
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
+indicates whether or not they are applicable to non-VMS systems.
 
 @menu
 * Ada Language Compatibility::
@@ -23343,7 +23346,8 @@ for Q'Address use Q_Address;
 @noindent
 which will be accepted by GNAT (and other Ada compilers), and is also
 compatible with Ada 83. A fuller description of the restrictions
-on address specifications is found in the @cite{GNAT Reference Manual}.
+on address specifications is found in @ref{Top, GNAT Reference Manual,
+About This Guide, gnat_rm, GNAT Reference Manual}.
 
 @node Other Representation Clauses
 @subsection Other Representation Clauses
@@ -23430,8 +23434,8 @@ pragma Extend_System (Aux_DEC);
 
 @noindent
 The pragma @code{Extend_System} is a configuration pragma that
-is most conveniently placed in the @file{gnat.adc} file. See the
-@cite{GNAT Reference Manual} for further details.
+is most conveniently placed in the @file{gnat.adc} file. @xref{Pragma
+Extend_System,,, gnat_rm, GNAT Reference Manual} for further details.
 
 HP Ada does not allow the recompilation of the package
 @code{SYSTEM}. Instead HP Ada provides several pragmas
@@ -23462,8 +23466,8 @@ are virtually identical to those provided by the HP Ada 83 package
 @code{TO_ADDRESS}
 function for type @code{UNSIGNED_LONGWORD} is changed to
 @code{TO_ADDRESS_LONG}.
-See the @cite{GNAT Reference Manual} for a discussion of why this change was
-necessary.
+@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual} for a
+discussion of why this change was necessary.
 
 @noindent
 The version of @code{TO_ADDRESS} taking a @i{universal_integer} argument
@@ -23792,8 +23796,9 @@ GNAT also supplies a number of implementation-defined pragmas as follows:
 @end itemize
 
 @noindent
-For full details on these GNAT implementation-defined pragmas, see
-the GNAT Reference Manual.
+For full details on these GNAT implementation-defined pragmas,
+see @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
+Manual}.
 
 @menu
 * Restrictions on the Pragma INLINE::
@@ -24035,8 +24040,7 @@ Interfacing to C with GNAT, you can use the above approach
 described for HP Ada or the facilities of Annex B of
 the @cite{Ada Reference Manual} (packages @code{INTERFACES.C},
 @code{INTERFACES.C.STRINGS} and @code{INTERFACES.C.POINTERS}). For more
-information, see the section ``Interfacing to C'' in the
-@cite{GNAT Reference Manual}.
+information, see @ref{Interfacing to C,,, gnat_rm, GNAT Reference Manual}.
 
 The @option{-gnatF} qualifier forces default and explicit
 @code{External_Name} parameters in pragmas @code{Import} and @code{Export}
@@ -24407,8 +24411,8 @@ by the @cite{Ada Reference Manual}.
 
 For further information on how GNAT interfaces to the file
 system or how I/O is implemented in programs written in
-mixed languages, see the chapter ``Implementation of the
-Standard I/O'' in the @cite{GNAT Reference Manual}.
+mixed languages, see @ref{Implementation of the Standard I/O,,,
+gnat_rm, GNAT Reference Manual}.
 This chapter covers the following:
 @itemize @bullet
 @item  Standard I/O packages
@@ -27739,8 +27743,9 @@ a pragma @code{Assert} that can be used for such tests. This pragma is modeled
 @cindex pragma @code{Assert}
 on the @code{Assert} pragma that has always been available in GNAT, so this
 feature may be used with GNAT even if you are not using Ada 2005 features.
-The use of pragma @code{Assert} is described in the
-@cite{GNAT Reference Manual}, but as an example, the last test could be written:
+The use of pragma @code{Assert} is described in
+@ref{Pragma Assert,,, gnat_rm, GNAT Reference Manual}, but as an
+example, the last test could be written:
 
 @smallexample @c ada
 pragma Assert (Temperature <= 999.0, "Temperature Crazy");
@@ -28206,7 +28211,8 @@ from which it generates a sequence of assembly language instructions.
 
 The examples in this chapter will illustrate several of the forms
 for invoking @code{Asm}; a complete specification of the syntax
-is found in the @cite{GNAT Reference Manual}.
+is found in @ref{Machine Code Insertions,,, gnat_rm, GNAT Reference
+Manual}.
 
 Under the standard GNAT conventions, the @code{Nothing} procedure
 should be in a file named @file{nothing.adb}.
@@ -29086,11 +29092,11 @@ transition from certain Ada 83 compilers.
 @noindent
 Ada compilers are allowed to supplement the language-defined pragmas, and
 these are a potential source of non-portability.  All GNAT-defined pragmas
-are described in the GNAT Reference Manual, and these include several that
-are specifically intended to correspond to other vendors' Ada 83 pragmas.
+are described in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT
+Reference Manual}, and these include several that are specifically
+intended to correspond to other vendors' Ada 83 pragmas.
 For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful.
-For
-compatibility with HP Ada 83, GNAT supplies the pragmas
+For compatibility with HP Ada 83, GNAT supplies the pragmas
 @code{Extend_System}, @code{Ident}, @code{Inline_Generic},
 @code{Interface_Name}, @code{Passive}, @code{Suppress_All},
 and @code{Volatile}.
@@ -29105,9 +29111,9 @@ relevant in a GNAT context and hence are not otherwise implemented.
 @subsection Implementation-defined attributes
 
 Analogous to pragmas, the set of attributes may be extended by an
-implementation.  All GNAT-defined attributes are described in the
-@cite{GNAT Reference Manual}, and these include several that are specifically
-intended
+implementation.  All GNAT-defined attributes are described in
+@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference
+Manual}, and these include several that are specifically intended
 to correspond to other vendors' Ada 83 attributes.  For migrating from VADS,
 the attribute @code{VADS_Size} may be useful.  For compatibility with HP
 Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and
@@ -29383,8 +29389,8 @@ Overview and Comparison on HP Platforms}.
 
 For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
 attributes are recognized, although only a subset of them can sensibly
-be implemented.  The description of pragmas in the
-@cite{GNAT Reference Manual}
+be implemented.  The description of pragmas in @ref{Implementation
+Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
 indicates whether or not they are applicable to non-VMS systems.
 @end ifclear
 

Re: [PATCH, ADA, DOC] PR 15479: Crossrefs and links

[Arnaud Charlet]

> Well, maybe, but the filename needs to be embedded (with @setfilename)
> in the input file of makeinfo already, so they really are related.

Right, and as I said, removing the setfilename instructions is fine.

> Alright.  I think the patch below does what you want.
> 
> Tested 'make info pdf dvi'.  OK for trunk?  What about 4.3?

OK for trunk, and OK on principle for 4.3. I do not know if you need an OK
from a release manager as well for 4.3.

Thanks for your work and iterations.

Arno