Tweaks for external xrefs.

git-svn-id: https://svn.r-project.org/R/trunk@84793 00db46b3-68df-0310-9c12-caf00c1e9a41

doc/manual/R-FAQ.texi

@@ -80,7 +80,7 @@ Kurt Hornik and the R Core Team @*
 <h2>Frequently Asked Questions on R</h2>
 <h3 style="text-align: center;">Version @value{FAQ_VERSION}</h3>
 <h3 style="text-align: center;">Kurt Hornik and the R Core Team</h3>
-<hr>
+<hr/>
 @end html
 @end ifhtml
 
@@ -1919,8 +1919,8 @@ structure, the configure and cleanup mechanisms, and on automated
 package checking and building.
 @end ifclear
 @ifset UseExternalXrefs
-@xref{Creating R packages, , Creating R packages, R-exts, Writing R
-Extensions}, for details.
+@xref{Creating R packages, , Creating R packages, R-exts, Writing R Extensions},
+for details.
 @end ifset
 
 R version 1.3.0 has added the function @code{package.skeleton()} which

doc/manual/R-admin.texi

@@ -1805,7 +1805,13 @@ installed version.
 @chapter Running R
 
 How to start @R{} and what command-line options are available is discussed
-in @ref{Invoking R, , Invoking R, R-intro, An Introduction to R}.
+in 
+@ifset UseExternalXrefs
+@ref{Invoking R, , Invoking R, R-intro, An Introduction to R}.
+@end ifset
+@ifclear UseExternalXrefs
+section `Invoking R' in the `An Introduction to R' manual.
+@end ifclear
 
 You should ensure that the shell has set adequate resource limits: @R{}
 expects a stack size of at least 8MB and to be able to open at least 256

doc/manual/R-exts.texi

@@ -113,6 +113,11 @@ the command @code{R CMD INSTALL}.
 @xref{Add-on packages, , Add-on-packages,
 R-admin, R Installation and Administration}.
 @end ifset
+@ifclear UseExternalXrefs
+See section `Add-on-packages' in the `R Installation and Administration'
+manual for more information.
+@end ifclear
+
 
 Other types of extensions are supported (but rare): @xref{Package types}.
 
@@ -205,10 +210,14 @@ package are created at installation time and stored in a database in the
 @file{R} directory of the installed package, being loaded into the
 session at first use. This makes the @R{} session start up faster and
 use less (virtual) memory.
-@ifset UseExternalXrefs
 (For technical details,
+@ifset UseExternalXrefs
 @pxref{Lazy loading, , Lazy loading, R-ints, R Internals}.)
 @end ifset
+@ifclear UseExternalXrefs
+see section `Lazy loading' in the `R Internals' manual.)
+@end ifclear
+
 
 @cindex CRAN
 @acronym{CRAN} is a network of WWW sites holding the @R{} distributions
@@ -2174,6 +2183,10 @@ these should be settable by users (sites) through appropriate personal
 @xref{Customizing package compilation, , Customizing package compilation,
 R-admin, R Installation and Administration},
 @end ifset
+@ifclear UseExternalXrefs
+See section `Customizing package compilation' in the `R Installation and
+Administration' manual for more information.
+@end ifclear
 
 There are some macros@footnote{in POSIX parlance: GNU @command{make}
 calls these `make variables'.} which are set whilst configuring the
@@ -3530,8 +3543,14 @@ Of course, released packages should be able to run at least their own
 examples. Each example is run in a `clean' environment (so earlier
 examples cannot be assumed to have been run), and with the variables
 @code{T} and @code{F} redefined to generate an error unless they are set
-in the example: @xref{Logical vectors, , Logical vectors, R-intro, An
-Introduction to R}.
+in the example:
+@ifset UseExternalXrefs
+@xref{Logical vectors, , Logical vectors, R-intro, An Introduction to R}.
+@end ifset
+@ifclear UseExternalXrefs
+See section `Logical vectors' in the `An Introduction to R' manual for
+more information.
+@end ifclear
 
 @item
 If the package sources contain a @file{tests} directory then the tests
@@ -3609,7 +3628,7 @@ setting environment variables @w{@env{_R_CHECK_*_}} as described in
 @ref{Tools, , Tools, R-ints, R Internals}:
 @end ifset
 @ifclear UseExternalXrefs
-`R Internals':
+section `Tools' in the `R Internals' manual:
 @end ifclear
 a set of these customizations similar to those used by @acronym{CRAN}
 can be selected by the option @option{--as-cran} (which works best if
@@ -5042,6 +5061,10 @@ personal @file{Makevars} files.
 @xref{Customizing package compilation, , Customizing package compilation,
 R-admin, R Installation and Administration},
 @end ifset
+@ifclear UseExternalXrefs
+See section `Customizing package compilation' in the `R Installation and
+Administration' manual for more information.
+@end ifclear
 
 Portable C++ code needs to follow both the 2011, 2014 and 2017 standards
 or to specify C+11/14/17/20 where available (which is not the case on
@@ -6722,8 +6745,8 @@ messages respectively to language with code @samp{@var{ll}}.
 R Installation and Administration}, for details of language codes.
 @end ifset
 @ifclear UseExternalXrefs
-See `Localization of messages' in `R Installation and Administration',
-for details of language codes.
+See `Localization of messages' in the `R Installation and
+Administration' manual for details of language codes.
 @end ifclear
 
 There is an @R{} function, @code{update_pkg_po} in package @pkg{tools},
@@ -8503,9 +8526,15 @@ Although the deparsing cannot do so, we recommend the consistent use of
 the preferred assignment operator @samp{<-} (rather than @samp{=}) for
 assignment. Many package authors use a version of Emacs (on a
 Unix-alike or Windows) to edit @R{} code, using the ESS[S] mode of the
-@acronym{ESS} Emacs package. See @ref{R coding standards, , R coding
-standards, R-ints, R Internals} for style options within the ESS[S] mode
-recommended for the source code of @R{} itself.
+@acronym{ESS} Emacs package. See 
+@ifset UseExternalXrefs
+@ref{R coding standards, , R coding standards, R-ints, R Internals}
+@end ifset
+@ifclear UseExternalXrefs
+section `R coding standards' in the `R Internals' manual
+@end ifclear
+for style options within the ESS[S] mode recommended for the source code
+of @R{} itself.
 
 
 
@@ -10401,11 +10430,15 @@ and Fortran. Use this @emph{via} @command{R CMD INSTALL --use-LTO} (but
 that does not apply if there is a @file{src/Makefile} file or a Windows
 analogue).
 
-To set up support on a Unix-alike,
+To set up support on a Unix-alike, see
 @ifset UseExternalXrefs
-@xref{Link-Time Optimization, , Link-Time Optimization,
+@ref{Link-Time Optimization, , Link-Time Optimization,
 R-admin, R Installation and Administration}.
 @end ifset
+@ifclear UseExternalXrefs
+section `Link-Time Optimization' in the `R Installation and
+Administration' manual.
+@end ifclear
 On Linux using GCC without building @R{} with LTO support,
 @c This will not set LTO for linking, but GCC does not seem to need that.
 it should suffice to set
@@ -10420,6 +10453,10 @@ in a personal (or site) @file{Makevars} file:
 @xref{Customizing package compilation, , Customizing package compilation,
 R-admin, R Installation and Administration},
 @end ifset
+@ifclear UseExternalXrefs
+See `Customizing package compilation' in the `R Installation and
+Administration' manual for more information.
+@end ifclear
 
 For Windows, first edit file @file{etc/$@{R_ARCH@}/Makeconf} to give
 @code{LTO_OPT} the value @code{-flto} or do so in a personal/site
@@ -11626,7 +11663,10 @@ makefiles or in a site-wide @file{Makevars.site} file.
 @xref{Customizing package compilation, , Customizing package compilation,
 R-admin, R Installation and Administration},
 @end ifset
-
+@ifclear UseExternalXrefs
+See `Customizing package compilation' in the `R Installation and
+Administration' manual for more information.
+@end ifclear
 
 Note that as @command{R CMD SHLIB} uses Make, it will not remake a shared
 object just because the flags have changed, and if @file{test.c} and
@@ -12163,8 +12203,14 @@ pointer to a structure with typedef @code{SEXPREC}. Think of this
 structure as a @emph{variant type} that can handle all the usual types
 of @R{} objects, that is vectors of various modes, functions,
 environments, language objects and so on. The details are given later
-in this section and in @ref{R Internal Structures, , R Internal
-Structures, R-ints, R Internals}, but for most
+in this section and in 
+@ifset UseExternalXrefs
+@ref{R Internal Structures, , R Internal Structures, R-ints, R Internals},
+@end ifset
+@ifclear UseExternalXrefs
+section `R Internal Structures' in the `R Internals' manual,
+@end ifclear
+but for most
 purposes the programmer does not need to know them. Think rather of a
 model such as that used by Visual Basic, in which @R{} objects are
 handed around in C code (as they are in interpreted @R{} code) as the
@@ -12413,8 +12459,13 @@ Among the important internal @code{SEXPTYPE}s are @code{LANGSXP},
 @code{CHARSXP}, @code{PROMSXP}, etc. (@strong{N.B.}: although it is
 possible to return objects of internal types, it is unsafe to do so as
 assumptions are made about how they are handled which may be violated at
-user-level evaluation.) More details are given in @ref{R Internal
-Structures, , R Internal Structures, R-ints, R Internals}.
+user-level evaluation.) More details are given in 
+@ifset UseExternalXrefs
+@ref{R Internal Structures, , R Internal Structures, R-ints, R Internals}.
+@end ifset
+@ifclear UseExternalXrefs
+section `R Internal Structures' in the `R Internals' manual.
+@end ifclear
 
 Unless you are very sure about the type of the arguments, the code
 should check the data types. Sometimes it may also be necessary to

doc/manual/R-intro.texi

@@ -213,8 +213,15 @@ references.
 There are now a number of books which describe how to use @R{} for data
 analysis and statistics, and documentation for @Sl{}/@SPLUS{} can
 typically be used with @R{}, keeping the differences between the @Sl{}
-implementations in mind. @xref{What documentation exists for R?, , ,
-R-FAQ, The R statistical system FAQ}.
+implementations in mind. 
+@ifset UseExternalXrefs
+@xref{What documentation exists for R?, , , R-FAQ, R FAQ}.
+@end ifset
+@ifclear UseExternalXrefs
+See section `What documentation exists for R?' in the `R FAQ' manual for
+more information.
+@end ifclear
+
 
 @node R and statistics, R and the window system, Related software and documentation, Introduction and preliminaries
 @section R and statistics
@@ -488,8 +495,14 @@ You can find out how to do this by reading the manual entry for the
 
 Alternatively, the Emacs text editor provides more general support
 mechanisms (via @acronym{ESS}, @emph{Emacs Speaks Statistics}) for
-working interactively with @R{}. @xref{R and Emacs, , , R-FAQ, The R
-statistical system FAQ}.
+working interactively with @R{}. 
+@ifset UseExternalXrefs
+@xref{R and Emacs, , , R-FAQ, R FAQ}.
+@end ifset
+@ifclear UseExternalXrefs
+See section `R and Emacs' in the `R FAQ' manual for more information.
+@end ifclear
+
 
 @node Executing commands from or diverting output to a file, Data permanency and removing objects, Recall and correction of previous commands, Introduction and preliminaries
 @section Executing commands from or diverting output to a file
@@ -6426,9 +6439,14 @@ when a package is loaded are its contents available. This is done both
 for efficiency (the full list would take more memory and would take
 longer to search than a subset), and to aid package developers, who are
 protected from name clashes with other code. The process of developing
-packages is described in @ref{Creating R packages, , Creating R
-packages, R-exts, Writing R Extensions}. Here, we will describe them
-from a user's point of view.
+packages is described in
+@ifset UseExternalXrefs
+@ref{Creating R packages, , Creating R packages, R-exts, Writing R Extensions}.
+@end ifset
+@ifclear UseExternalXrefs
+section `Creating R packages' in the `Writing R Extensions' manual.
+@end ifclear
+Here, we will describe them from a user's point of view.
 
 To see which packages are installed at your site, issue the command
 
@@ -6491,8 +6509,15 @@ The standard (or @emph{base}) packages are considered part of the @R{}
 source code. They contain the basic functions that allow @R{} to work,
 and the datasets and standard statistical and graphical functions that
 are described in this manual. They should be automatically available in
-any @R{} installation. @xref{Which add-on packages exist for R?, , R
-packages, R-FAQ, R FAQ}, for a complete list.
+any @R{} installation. 
+For a complete list, see
+@ifset UseExternalXrefs
+@ref{Which add-on packages exist for R?, , R packages, R-FAQ, R FAQ}.
+@end ifset
+@ifclear UseExternalXrefs
+section `Which add-on packages exist for R?' in the `R FAQ' manual.
+@end ifclear
+
 
 @node Contributed packages and CRAN, Namespaces, Standard packages, Packages
 @section Contributed packages and @acronym{CRAN}

doc/manual/R-ints.texi

@@ -1614,7 +1614,7 @@ recommended in
 @ref{Memory allocation, , Memory allocation, R-exts, Writing R Extensions}
 @end ifset
 @ifclear UseExternalXrefs
-`Writing R Extensions'
+section `Memory allocation' in the `Writing R Extensions' manual
 @end ifclear
 @findex R_alloc
 @findex R_Calloc
@@ -1845,7 +1845,7 @@ We make use of the visibility mechanisms discussed in
 @ref{Controlling visibility, , Controlling visibility, R-exts, Writing R Extensions},
 @end ifset
 @ifclear UseExternalXrefs
-section `Controlling Visibility' in `Writing R Extensions',
+section `Controlling Visibility' in the `Writing R Extensions' manual,
 @end ifclear
 C entry points not needed outside the main @R{} executable/dynamic
 library (and in particular in no package nor module) should be prefixed
@@ -2384,7 +2384,7 @@ in an @R{} package is described in
 @ref{Internationalization, , Internationalization, R-exts, Writing R Extensions},
 @end ifset
 @ifclear UseExternalXrefs
-`Writing R Extensions',
+section `Internationalization' in the `Writing R Extensions' manual,
 @end ifclear
 and the standard packages included with @R{} have (with an exception in
 @pkg{grDevices} for the menus of the @code{windows()} device) been
@@ -2512,9 +2512,15 @@ See file @file{po/README} for how to update the message templates and catalogs.
 * Help:: 
 @end menu
 
-The structure of a @emph{source} packages is described in @ref{Creating
-R packages, , Creating R packages, R-exts, Writing R Extensions}: this
-chapter is concerned with the structure of @emph{installed} packages.
+The structure of a @emph{source} packages is described in 
+@ifset UseExternalXrefs
+@ref{Creating R packages, , Creating R packages, R-exts, Writing R Extensions}: 
+@end ifset
+@ifclear UseExternalXrefs
+section `Creating R packages' in the `Writing R Extensions' manual:
+@end ifclear
+this chapter is concerned with the structure of @emph{installed}
+packages. 
 
 An installed package has a top-level file @file{DESCRIPTION}, a copy of
 the file of that name in the package sources with a @samp{Built} field
@@ -4305,7 +4311,7 @@ See
 @ref{Writing portable packages, , Writing portable packages, R-exts, Writing R Extensions}
 @end ifset
 @ifclear UseExternalXrefs
-`Writing R Extensions'
+section `Writing portable packages' in the `Writing R Extensions' manual
 @end ifclear
 for the rationale of this check (and why even @option{-Werror} is
 unsafe).