I have attached a patch (svn diff) containing some edits of
R-exts.texi to fix minor grammatical errors (I changed a lot of
"which"s to "that"s) and to improve readability (I hope). When
unsure, I have tried to avoid making changes that might affect
meaning, so I hope that this patch will not be controversial.
I have a few other comments, concerning points where I did not make
any changes, but where I think some further (minor) editing is needed.
These are listed below, with approximated line numbers from
R-exts.texi in the current development trunk (revision 40804). I
could come up with my own edits for at least the first and third of
these comments/questions, but I was less sure that such edits would be
welcome.
Line 453:
The statement
Non-ASCII characters in object names will normally fail when the
package is installed.
needs to be more precise. Does the installation fail, or is the
object left undefined, or what? "Non-ASCII characters" will "fail"
doesn't make much sense to me.
Line 793:
What does this comment mean?
(and hence e.g.@: removed from @code{ACX_BLAS})
Lines 1182, 1787, and elsewhere:
This is picky, but shouldn't "DLL" be "shared library/DLL" or "shared
object/DLL" (as at line 811), or even ".so/DLL". Alternatively, maybe
it should be stated somewhere early in the document that DLL may be
used to refer to both Windows DLLs and Unix shared object libraries.
Of course, some of us might prefer to have things the other way
around: isn't "shared library" more generic than "DLL"?
---
Brett Presnell
Department of Statistics
University of Florida
http://www.stat.ufl.edu/~presnell/
"We don't think that the popularity of an error makes it the truth."
-- Richard Stallman
() ascii ribbon campaign - against html mail
/\ - against microsoft attachments
Index: doc/manual/R-exts.texi
===================================================================
--- doc/manual/R-exts.texi (revision 40804)
+++ doc/manual/R-exts.texi (working copy)
@@ -158,7 +158,7 @@
@cindex cleanup file
The optional files @file{configure} and @file{cleanup} are (Bourne
-shell) script files which are executed before and (provided that option
+shell) script files that are executed before and (provided that option
@option{--clean} was given) after installation on Unix-alikes, see
@ref{Configure and cleanup}.
@@ -276,17 +276,17 @@
etc.). It should not end in a period or comma.
The optional @samp{Date} field gives the release date of the current
-version of the package. It is strongly recommended to use the yyyy-mm-dd
-format conforming to the ISO standard.
+version of the package. Use of the yyyy-mm-dd format, conforming to the
+ISO standard, is strongly recommended.
The optional @samp{Depends} field gives a comma-separated list of
-package names which this package depends on. The package name may be
+packages that this package depends on. The package name may be
optionally followed by a comparison operator (currently only @samp{>=}
and @samp{<=} are supported), whitespace and a valid version number in
parentheses. (List package names even if they are part of a bundle.)
You can also use the special package name @samp{R} if your package
-depends on a certain version of @R{}. E.g., if the package works only with
[EMAIL PROTECTED] version 2.4.0 or newer, include @samp{R (>= 2.4.0)} in the
+depends on a certain version of @R{}. E.g., if the package works only
+with @R{} version 2.4.0 or newer, include @samp{R (>= 2.4.0)} in the
@samp{Depends} field. Both @code{library} and the @R{} package checking
facilities use this field, hence it is an error to use improper syntax
or misuse the @samp{Depends} field for comments on other software that
@@ -294,8 +294,8 @@
should be listed in the @samp{SystemRequirements} field or a separate
@file{README} file. The @R{} @command{INSTALL} facilities check if the
version of @R{} used is recent enough for the package being installed,
-and the list of packages which is specified will be attached (after
-checking version dependencies) before the current package, both when
+and the list of packages specified will be attached (after checking
+version dependencies) before the current package, both when
@code{library} is called and when saving an image of the package's code
or preparing for lazy-loading.
@@ -329,13 +329,13 @@
@code{library(@var{pkgname})} must be listed in the @samp{Imports}
field.
@item
-Packages that need to be attached to successfully load the package using
+Packages that need to be attached to load the package using
@code{library(@var{pkgname})} must be listed in the @samp{Depends}
field.
@item
-All packages that are needed to successfully run @code{R CMD check} on
-the package must be listed in one of @samp{Depends} or @samp{Suggests}
-or @samp{Imports}.
+All packages that are needed to run @code{R CMD check} on the package
+must be listed in one of @samp{Depends} or @samp{Suggests} or
[EMAIL PROTECTED]
@end itemize
@noindent
@@ -350,8 +350,8 @@
@acronym{CRAN}.
Base and recommended packages (i.e., packages contained in the @R{}
-source distribution or available from @acronym{CRAN} and recommended to
-be included in every binary distribution of @R{}) have a @samp{Priority}
+source distribution or available from @acronym{CRAN} and recommended for
+inclusion in every binary distribution of @R{}) have a @samp{Priority}
field with value @samp{base} or @samp{recommended}, respectively. These
priorities must not be used by ``other'' packages.
@@ -365,9 +365,8 @@
into account, see @ref{Package subdirectories}) as a whitespace
separated list of file paths relative to the @file{R} subdirectory.
@c % double quotes are not allowed in path names, for Windows
-Paths containing white space or quotes need to be quoted. An applicable
-OS-specific collation field (@samp{Collate.unix} or
[EMAIL PROTECTED]) will be used instead of @samp{Collate}.
+Paths containing white space or quotes need to be
+quoted. Applicable OS-specific collate specifications take precedence.
The optional @samp{LazyLoad} and @samp{LazyData} fields control whether
the @R{} objects and the datasets (respectively) use lazy-loading: set
@@ -450,16 +449,18 @@
Only @acronym{ASCII} characters (and the control characters tab,
formfeed, LF and CR) should be used in code files. Other characters are
accepted in comments, but then the comments may not be readable in
-e.g.@: a UTF-8 locale. [EMAIL PROTECTED] characters in object names
-will [EMAIL PROTECTED] is true for OSes which implement the
[EMAIL PROTECTED] locale, unless neither lazy-loading nor saving an image are
+e.g.@: a UTF-8 locale. Object names containing [EMAIL PROTECTED]
+characters will [EMAIL PROTECTED] is true for OSes that implement
+the @samp{C} locale, unless neither lazy-loading nor saving an image are
used, in which case it would fail if loaded in a @samp{C}
locale. (Windows' idea of the @samp{C} locale uses the WinAnsi
-charset.)} fail when the package is installed. Any byte will be
+charset.)} [EMAIL PROTECTED] more precise. Does the package installation
+fail, or will the object left undefined, or what? What does fail mean
+here?} when the package is installed. Any byte will be
[EMAIL PROTECTED] is good practice to encode them as octal or hex
-escape sequences.} in a quoted character string (but @code{\uxxxx}
-escapes should not be used), but [EMAIL PROTECTED] character strings
-may not be usable in some locales and may display incorrectly in others.
+escape sequences; @code{\uxxxx} escapes should not be used.} in a quoted
+character string, but [EMAIL PROTECTED] character strings may not be
+usable in some locales and may display incorrectly in others.
@findex .First.lib
@@ -492,13 +493,13 @@
- _ . + ! ' ( ) , ; @ = &}.} they must be entirely @acronym{ASCII} and
not contain @samp{%}. @xref{Writing R documentation files}, for more
information. Note that all user-level objects in a package should be
-documented; if a package @var{pkg} contains user-level objects which are
+documented; if a package @var{pkg} contains user-level objects that are
for ``internal'' use only, it should provide a file
[EMAIL PROTECTED]@var{pkg}-internal.Rd} which documents all such objects, and
[EMAIL PROTECTED]@var{pkg}-internal.Rd} that documents all such objects and that
clearly states that these are not meant to be called by the user. See
e.g.@: the sources for package @pkg{grid} in the @R{} distribution for
-an example. Note that packages which use internal objects extensively
-should hide those objects in a name space, when they do not need to be
+an example. Note that packages that use internal objects extensively
+should hide those objects in a name space when they do not need to be
documented (@pxref{Package name spaces}).
The @file{R} and @file{man} subdirectories may contain OS-specific
@@ -526,7 +527,7 @@
mechanism should be general enough to eliminate the need for a
package-specific @file{Makefile}. If such a file is to be distributed,
considerable care is needed to make it general enough to work on all
[EMAIL PROTECTED] platforms. In addition, it should have a target @samp{clean}
which
[EMAIL PROTECTED] platforms. In addition, it should have a target @samp{clean}
that
removes all files generated by Make. If necessary, platform-specific
files can be used, for example @file{Makevars.win} or
@file{Makefile.win} on Windows take precedence over @file{Makevars} or
@@ -588,7 +589,7 @@
and then calling them with the strangest arguments). The results of
running a @file{.R} file are written to a @file{.Rout} file. If there
is a corresponding @file{.Rout.save} file, these two are compared, with
-differences being reported but not causing an error. The whose
+differences being reported but not causing an error. The subdirectory
@file{tests} is copied to the check area, and the tests are run with the
copy as the working directory and with @code{R_LIBS} set to ensure that
the copy of the package installed during testing will be found by
@@ -607,7 +608,7 @@
@cindex Package bundles
Sometimes it is convenient to distribute several packages as a
[EMAIL PROTECTED] (An example is @pkg{VR} which contains four packages.)
[EMAIL PROTECTED] (An example is @pkg{VR}, which contains four packages.)
The installation procedures on both Unix-alikes and Windows can handle
package bundles.
@@ -644,8 +645,8 @@
The packages contained in a bundle are standard packages in all
respects except that the @file{DESCRIPTION} file is replaced by a
[EMAIL PROTECTED] file which just contains fields additional to
-the @file{DESCRIPTION} file of the bundle, for example
[EMAIL PROTECTED] file that just contains fields additional to
+the @file{DESCRIPTION} file of the bundle; for example:
@quotation
@cartouche
@@ -689,15 +690,15 @@
its source. It can be used to clean up the package source tree. In
particular, it should remove all files created by @command{configure}.
-As an example consider we want to use functionality provided by a (C or
-FORTRAN) library @code{foo}. Using Autoconf, we can create a configure
-script which checks for the library, sets variable @code{HAVE_FOO} to
[EMAIL PROTECTED] if it was found and with @code{FALSE} otherwise, and then
-substitutes this value into output files (by replacing instances of
[EMAIL PROTECTED]@@HAVE_FOO@@} in input files with the value of
@code{HAVE_FOO}).
-For example, if a function named @code{bar} is to be made available by
-linking against library @code{foo} (i.e., using @option{-lfoo}), one
-could use
+As an example, suppose that we want to use functionality provided by a
+(C or FORTRAN) library @code{foo}. Using Autoconf, we can create a
+configure script that checks for the library, sets variable
[EMAIL PROTECTED] to @code{TRUE} if it was found and to @code{FALSE}
+otherwise, and then substitutes this value into output files (by
+replacing instances of @samp{@@HAVE_FOO@@} in input files with the value
+of @code{HAVE_FOO}). For example, if a function named @code{bar} is to
+be made available by linking against library @code{foo} (i.e., using
[EMAIL PROTECTED]), one could use
@example
@group
@@ -772,7 +773,7 @@
@[EMAIL PROTECTED]/etc/Makeconf}, which only works for variables
recorded there as literals. You can use @code{R CMD config} for getting
the value of the basic configuration variables, or the header and
-library flags necessary for linking against @R{}, see @kbd{R CMD config
+library flags necessary for linking against @R{}; see @kbd{R CMD config
--help} for details.
To check for an external BLAS library using the @code{ACX_BLAS} macro
@@ -855,7 +856,7 @@
compiler: flags such as @option{-O2 -Wall -pedantic} are all specific to
GCC.
-There are some macros which are built whilst configuring the building of
+There are some macros that are built whilst configuring the building of
@R{} itself, are stored on Unix-alikes in
@[EMAIL PROTECTED]/etc/Makeconf} and can be used in @file{Makevars}.
These include
@@ -881,9 +882,9 @@
A macro containing the LAPACK libraries (and paths where appropriate)
used when building @R{}. This may need to be included in
@code{PKG_LIBS}. This may point to a dynamic library @code{libRlapack}
-which contains all the double-precision LAPACK routines as well as those
-double-complex LAPACK and BLAS routines needed to build @R{}, or it
-may point to an external LAPACK library, or may be empty if an external
+that contains all the double-precision LAPACK routines as well as those
+double-complex LAPACK and BLAS routines needed to build @R{}, or it may
+point to an external LAPACK library, or it may be empty if an external
BLAS library also contains LAPACK.
[There is no guarantee that the LAPACK library will provide more than
@@ -895,7 +896,7 @@
@item SAFE_FFLAGS
@vindex SAFE_FFLAGS
-A macro containing flags which are needed to circumvent
+A macro containing flags that are needed to circumvent
over-optimization of Fortran code: it is typically @samp{-g -O2
-ffloat-store} on @cputype{ix86} platforms using @command{g77} or
@command{gfortran}.
@@ -1069,7 +1070,7 @@
On some systems an alternative F95 compiler is available: from the
@code{gcc} family this might be @command{gfortran} or @command{g95}.
-Configuring @R{} will try to find a compiler which (from its name)
+Configuring @R{} will try to find a compiler that (from its name)
appears to be a Fortran 90/95 compiler, and set it in macro @samp{FC}.
Note that it does not check that such a compiler is fully (or even
partially) compliant with Fortran 90/95. Packages making use of
@@ -1133,7 +1134,7 @@
run time. One check is that the package name is not that of a standard
package, nor of the defunct standard packages (@samp{ctest}, @samp{eda},
@samp{lqs}, @samp{mle}, @samp{modreg}, @samp{mva}, @samp{nls},
[EMAIL PROTECTED] and @samp{ts}) which are handled specially by
[EMAIL PROTECTED] and @samp{ts}), which are handled specially by
@code{library}. Another check is that all packages mentioned in
@code{library} or @code{requires} or from which the @file{NAMESPACE}
file imports or are called @emph{via} @code{::} or @code{:::} are listed
@@ -1159,7 +1160,7 @@
ending in @samp{.in} will be allowed in the @file{R} directory.
@item
-The @R{} files are checked for syntax errors. Bytes which are
+The @R{} files are checked for syntax errors. Bytes that are
[EMAIL PROTECTED] are reported as warnings, but these should be
regarded as errors unless it is known that the package will always be
used in the same locale.
@@ -1260,19 +1261,20 @@
to be up-to-date, and C, C++ and FORTRAN source files are tested and
converted to LF line-endings if necessary.
-Run-time checks whether the package works correctly should be performed
-using @code{R CMD check} prior to invoking the build procedure.
+Run-time checks of whether the package works correctly should be
+performed using @code{R CMD check} prior to invoking the build
+procedure.
-To exclude files from being put into the package, one can specify a list
-of exclude patterns in file @file{.Rbuildignore} in the top-level source
-directory. These patterns should be Perl regexps, one per line, to be
-matched against the file names relative to the top-level source
-directory. In addition, directories called @file{CVS} or @file{.svn} or
+To exclude files from the package, one can specify a list of exclude
+patterns in file @file{.Rbuildignore} in the top-level source directory.
+These patterns should be Perl regexps, one per line, to be matched
+against the file names relative to the top-level source directory. In
+addition, directories called @file{CVS} or @file{.svn} or
@file{.arch-ids} and files @file{GNUMakefile} or with base names
starting with @samp{.#}, or starting and ending with @samp{#}, or ending
in @samp{~}, @samp{.bak} or @samp{.swp}, are excluded by default. In
addition, those files in the @file{R}, @file{demo} and @file{man}
-directories which are flagged by @code{R CMD check} as having invalid
+directories that are flagged by @code{R CMD check} as having invalid
names will be excluded.
@c <FIXME>
@@ -1300,7 +1302,7 @@
It can be useful to run @code{R CMD check --check-subdirs=yes} on the
built tarball as a final check on the contents.
[EMAIL PROTECTED] CMD build} can also build pre-compiled version of packages for
[EMAIL PROTECTED] CMD build} can also build pre-compiled versions of packages
for
binary distributions, but @code{R CMD INSTALL --build} is preferred (and
is considerably more flexible). In particular, Windows users are
recommended to use @code{R CMD INSTALL --build} and install into the
@@ -1387,48 +1389,48 @@
@cindex Sweave
In addition to the help files in Rd format, @R{} packages allow the
-inclusion of documents in arbitrary other formats. The standard
-location for these is subdirectory @file{inst/doc} of a source package,
-the contents will be copied to subdirectory @file{doc} when the package
-is installed. Pointers from package help indices to the installed
-documents are automatically created. Documents in @file{inst/doc} can
-be in arbitrary format, however we strongly recommend to provide them in
-PDF format, such that users on all platforms can easily read them. To
+inclusion of documents in other formats. The standard location for
+these is the subdirectory @file{inst/doc} of a source package, and the
+contents of this subdirectory are copied to the subdirectory @file{doc}
+when the package is installed. Pointers from package help indices to
+the installed documents are automatically created. Documents in
[EMAIL PROTECTED]/doc} can be in any arbitrary format, but we strongly
+recommend PDF, so that users on all platforms can easily read them. To
ensure that they can be accessed from a browser, the file names should
-start with an @acronym{ASCII} letter and be entirely in @acronym{ASCII}
-letters or digits or minus or underscore.
+start with an @acronym{ASCII} letter and contain only @acronym{ASCII}
+letters, digits, minus, and underscore.
-A special case are documents in Sweave format, which we call
+Documents in Sweave format constitute a special case and are called
@emph{package vignettes}. Sweave allows the integration of @LaTeX{}
-documents and @R{} code and is contained in package @pkg{utils} which is
-part of the base @R{} distribution, see the @code{Sweave} help page for
-details on the document format. Package vignettes found in directory
[EMAIL PROTECTED]/doc} are tested by @code{R CMD check} by executing all @R{}
-code chunks they contain to ensure consistency between code and
-documentation. Code chunks with option @code{eval=FALSE} are not
-tested. The @R{} working directory for all vignette tests in @code{R CMD
-check} is the @emph{installed} version of the @file{doc}
-subdirectory. Make sure all files needed by the vignette (data sets,
[EMAIL PROTECTED]) are accessible by either placing them in the @file{inst/doc}
-hierarchy of the source package, or using calls to @code{system.file()}.
+documents and @R{} code and is contained in package @pkg{utils}, which
+is part of the base @R{} distribution; see the @code{Sweave} help page
+for details on the document format. @code{R CMD check} tests package
+vignettes found in the directory @file{inst/doc} by executing their @R{}
+code chunks to ensure consistency between code and documentation. Code
+chunks with the option @code{eval=FALSE} are not tested. The @R{}
+working directory for all vignette tests by @code{R CMD check} is the
[EMAIL PROTECTED] version of the @file{doc} subdirectory. Make sure that
+all files needed by the vignette (data sets, @dots{}) are accessible,
+either by placing them in the @file{inst/doc} hierarchy of the source
+package or by using calls to @code{system.file()}.
@code{R CMD build} will automatically create PDF versions of the
-vignettes for distribution with the package sources. By including the
-PDF version in the package sources it is not necessary that the
-vignettes can be compiled at install time, i.e., the package author can
-use private @LaTeX{} extensions which are only available on his machine.
-Only the @R{} code inside the vignettes is part of the checking
-procedure, typesetting manuals is not part of the package quality
-control.
+vignettes for distribution with the package sources. If a PDF version
+of the vignette is included in the package sources, it is not necessary
+for the vignettes to be compilable at install time, i.e., the package
+author can use private @LaTeX{} extensions that are only available on
+his machine. @code{R CMD check} evaluates only the @R{} code inside
+the vignettes, so assuring that manuals can be typeset is not a part of
+package checking.
By default @code{R CMD build} will run @code{Sweave} on all files in
Sweave format. If no @file{Makefile} is found in directory
@file{inst/doc}, then @code{texi2dvi --pdf} is run on all vignettes.
Whenever a @file{Makefile} is found, then @code{R CMD build} will try to
-run @command{make} after the @code{Sweave} step, such that PDF manuals
+run @command{make} after the @code{Sweave} step, so that PDF manuals
can be created from arbitrary source formats (plain @LaTeX{} files,
@dots{}). The @file{Makefile} should take care of both creation of PDF
-files and cleaning up afterwards, i.e., delete all files that shall not
+files and cleaning up afterwards, i.e., delete all files that should not
appear in the final package archive. Note that the @code{make} step is
executed independently from the presence of any files in Sweave format.
@@ -1437,12 +1439,12 @@
automatically from the @code{\VignetteIndexEntry} statements in all
Sweave files when installing from source, or when using the package
builder (@pxref{Checking and building packages}). The
[EMAIL PROTECTED] statement is best placed in @LaTeX{} comment,
-such that no definition of the command is necessary.
[EMAIL PROTECTED] statement is best placed in a @LaTeX{}
+comment, so that no definition of the command is necessary.
At install time an @HTML{} index for all vignettes is automatically
-created from the @code{\VignetteIndexEntry} statements unless a file
[EMAIL PROTECTED] exists in directory @file{inst/doc}. This index is
+created from the @code{\VignetteIndexEntry} statements, unless a file
[EMAIL PROTECTED] exists in the directory @file{inst/doc}. This index is
linked into the @HTML{} help system for each package.
@node Submitting a package to CRAN, Package name spaces, Writing package
vignettes, Creating R packages
@@ -1456,9 +1458,9 @@
encouraged to join in the collaborative project and to submit their own
packages to @acronym{CRAN}.
-Before submitting a package @pkg{mypkg}, do run the following steps to
-test it is complete and will install properly. (Unix procedures only,
-run from the directory containing @file{mypkg} as a subdirectory.)
+Before submitting a package @pkg{mypkg}, run the following steps to test
+that it is complete and will install properly. (Unix procedures only,
+to be run from the directory containing @file{mypkg} as a subdirectory.)
@enumerate
@item
@@ -1481,8 +1483,9 @@
principle, packages must pass @code{R CMD check} without warnings to be
admitted to the main @acronym{CRAN} package area.
-When all the testing is done, upload the @file{.tar.gz} file, using
[EMAIL PROTECTED] as log-in name and your e-mail address as password, to
+When all testing is successfully completed, upload the @file{.tar.gz}
+file, using @samp{anonymous} as log-in name and your e-mail address as
+password, to
@example
@url{ftp://cran.R-project.org/incoming/}
@@ -1616,7 +1619,7 @@
Variables exported from other packages with name spaces need to be
imported explicitly using the directives @code{import} and
@code{importFrom}. The @code{import} directive imports all exported
-variables from the specified package(s). Thus the directives
+variables from the specified package(s). Thus the directive
@findex import
@example
@@ -1638,7 +1641,7 @@
specifies that the exported variables @code{f} and @code{g} of the
package @pkg{foo} are to be imported.
-If a package only needs one (exported) object from another package it
+If a package needs only one (exported) object from another package it
can use a fully qualified variable reference in the code instead of a
formal import. A fully qualified reference to the function @code{f} in
package @pkg{foo} is of the form @code{foo::f}. This is less efficient
@@ -1692,7 +1695,7 @@
@findex .Last.lib
@findex .onUnload
However, packages with name spaces @emph{do} use the @code{.Last.lib}
-function. There is also a hook @code{.onUnload} which is called when
+function. There is also a hook @code{.onUnload} that is called when
the name space is unloaded (via a call to @code{unloadNamespace}) with
argument the full path to the directory in which the package was
installed. @code{.onUnload} should be defined in the name space and not
@@ -1703,7 +1706,7 @@
placed in a @code{.onLoad} function, or use made of the @code{useDynLib}
directive described next.
-There can be one or more @code{useDynLib} directives which allow shared
+There can be one or more @code{useDynLib} directives that allow shared
objects that need to be loaded to be specified in the @file{NAMESPACE}
file. The directive
@@ -1725,12 +1728,13 @@
The @code{useDynLib} directive also accepts the names of the native
routines that are to be used in @R{} via the @code{.C}, @code{.Call},
@code{.Fortran} and @code{.External} interface functions. These are given as
-additional arguments to the directive, for example,
+additional arguments to the directive, as in
@example
useDynLib(foo, myRoutine, myOtherRoutine)
@end example
[EMAIL PROTECTED]
By specifying these names in the @code{useDynLib} directive, the
native symbols are resolved when the package is loaded and @R{} variables
identifying these symbols are added to the package's name space with
@@ -1751,6 +1755,7 @@
.Call("myRoutine", x, y, PACKAGE = "foo")
@end example
[EMAIL PROTECTED]
There are at least two benefits to this approach. Firstly, the symbol
lookup is done just once for each symbol rather than each time it the
routine is invoked. Secondly, this removes any ambiguity in resolving
@@ -1771,6 +1776,7 @@
useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)
@end example
[EMAIL PROTECTED]
We could then call that routine from @R{} using the command
@example
@@ -1781,18 +1787,19 @@
that name.
In some cases, it may be preferable not to create @R{} variables in the
-package's name space that identify the native routines. It may be too
-costly to compute these for many routines when the package is loaded
-if many of these routines are not likely to be used. In this case,
-one can still perform the symbol resolution correctly using the DLL,
-but do this each time the routine is called. Given a reference to the
-DLL as an @R{} variable, say @code{dll}, we can call the routine
[EMAIL PROTECTED] using the expression
+package's name space that identify the native routines. For example, it
+may be too costly to compute these when there are many such routines, a
+large number of which are unlikely to be used. In this case, one can
+still perform the symbol resolution correctly using the DLL, but do this
+each time the routine is called. Given a reference to the DLL as an
[EMAIL PROTECTED] variable, say @code{dll}, we can call the routine
@code{myRoutine}
+using the expression
@example
.Call(dll$myRoutine, x, y)
@end example
[EMAIL PROTECTED]
The @code{$} operator resolves the routine with the given name in the
DLL using a call to @code{getNativeSymbol}. This is the same
computation as above where we resolve the symbol when the package is
@@ -1811,6 +1818,7 @@
myDLL = useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)
@end example
[EMAIL PROTECTED]
Then, the @R{} variable @code{myDLL} is in the package's name space and
available for calls such as @code{myDLL$dynRoutine} to access routines
that are not explicitly resolved at load time.
@@ -1823,9 +1831,11 @@
with the address of the routine and any information about the number and
type of the parameters. Using the @code{.registration} argument of
@code{useDynLib}, we can instruct the name space mechanism to create
[EMAIL PROTECTED] variables for these symbols. For example, suppose we have the
-following registration information for a DLL named @code{myDLL}:
[EMAIL PROTECTED] variables for these symbols.
+For example, suppose we have the following registration information for
+a DLL named @code{myDLL}:
+
@example
R_CMethodDef cMethods[] = @{
@{"foo", &foo, 4, @{REALSXP, INTSXP, STRSXP, [EMAIL PROTECTED]@},
@@ -1840,16 +1850,17 @@
@};
@end example
-Then, the directive in the @file{NAMESPACE} file
[EMAIL PROTECTED]
+Then, the following directive in the @file{NAMESPACE} file
@example
useDynLib(myDLL, .registration = TRUE)
@end example
@noindent
-causes the DLL to be loaded and also for the @R{} variables @code{foo},
[EMAIL PROTECTED], @code{R_call_sym} and @code{R_version_sym} to be
-defined in the package's name space.
+causes the DLL to be loaded and the @R{} variables @code{foo},
[EMAIL PROTECTED], @code{R_call_sym} and @code{R_version_sym} to be defined
+in the package's name space.
Note that the names for the @R{} variables are taken from the entry in
the registration information and do not need to be the same as the name
@@ -1982,7 +1993,7 @@
@node Name spaces with formal classes and methods, , Summary -- converting an
existing package, Package name spaces
@subsection Name spaces with formal classes and methods
-Some additional steps are needed for packages which make use of formal
+Some additional steps are needed for packages that make use of formal
(S4-style) classes and methods (unless these are purely used
internally). There needs to be an @code{.onLoad} action to
ensure that the methods package is loaded @emph{and} attached:
@@ -1992,7 +2003,7 @@
@end example
@noindent
-and any classes and methods which are to be exported need to be declared
+and any classes and methods that are to be exported need to be declared
as such in the @file{NAMESPACE} file. For example, the now-defunct
@pkg{mle} package had
@@ -2105,7 +2116,7 @@
@item
Errors in memory allocation and reading/writing outside arrays are very
common causes of crashes (e.g., segfaults) on some machines.
-See @ref{Using valgrind} for a tool which can be used to look for this.
+See @ref{Using valgrind} for a tool that can be used to look for this.
@item
The Mac OS X linker has some restrictions not found on other platforms.
@@ -2174,12 +2185,12 @@
such users would have their computers set to a French locale, but let us
assume so. The problem then is that there are several possible
encodings for French locales, the most common ones being @samp{CP1252}
-(Windows), @samp{ISO 8859-1} (latin-1), @samp{ISO 8859-9} (latin-9 which
-includes the Euro), and @samp{UTF-8}. For characters in the French
-language the first three agree, but they do not agree with @samp{UTF-8}.
-Further, you (or different users) can run @R{} in different locales in
-different sessions, say @samp{fr_CA.utf8} one day and
[EMAIL PROTECTED] the next. As from @R{} 2.5.0, declaring the
+(Windows), @samp{ISO 8859-1} (latin-1), @samp{ISO 8859-9} (latin-9,
+which includes the Euro), and @samp{UTF-8}. For characters in the
+French language the first three agree, but they do not agree with
[EMAIL PROTECTED] Further, you (or different users) can run @R{} in
+different locales in different sessions, say @samp{fr_CA.utf8} one day
+and @samp{fr_CH.iso88591} the next. As from @R{} 2.5.0, declaring the
encoding as either @samp{latin1} or @samp{UTF-8} in the
@file{DESCRIPTION} file will enable this to work. If you have character
data in @file{.rda} files (for use by @code{data} or LazyData) these
@@ -2272,7 +2283,7 @@
@item
Occasionally messages need to be singular or plural (and in other
languages there may be no such concept or several plural forms --
-Slovenian has four). So avoid constructions such as was once used in
+Slovenian has four). So avoid constructions such as that once used in
@code{library}
@example
@@ -2288,7 +2299,7 @@
@end example
@noindent
-and was replaced by
+which was replaced by
@example
if((length(nopkgs) > 0) && !missing(lib.loc)) @{
@@ -2316,8 +2327,8 @@
(which is requested by @command{configure} option @option{--enable-nls},
the default).
-The procedures make use of @code{msgfmt} and @code{xgettext} which are
-part of @acronym{GNU} @code{gettext} and this will need to be installed:
+The procedures make use of @code{msgfmt} and @code{xgettext}; these are
+part of @acronym{GNU} @code{gettext}, which will need to be installed.
Windows users can find pre-compiled binaries at the @acronym{GNU}
archive mirrors and packaged with the @code{poEdit} package
(@url{http://@/poedit.sourceforge.net/@/download.php#win32}).
@@ -2331,7 +2342,7 @@
@node C-level messages, R messages, Localization, Localization
@subsection C-level messages
-The process of enabling translations is
+To enable translations of C-level messages:
@itemize
@item
@@ -2401,7 +2412,7 @@
@code{xgettext} extracts the actual calls and so is more useful when
tidying up error messages.
-Translation of messages which might be singular or plural can be very
+Translation of messages that might be singular or plural can be very
intricate: languages can have up to four different forms. The @R{}
function @code{ngettext} provides an interface to the C function of the
same name, and will choose an appropriate singular or plural form for
@@ -2506,13 +2517,13 @@
script @command{Rdconv} in @[EMAIL PROTECTED]/bin} and by the
installation scripts for packages.
-The @R{} distribution contains more than 1200 such files which can be
-found in the @file{src/library/@var{pkg}/man} directories of the @R{}
-source tree, where @var{pkg} stands for the standard packages which are
-included in the @R{} distribution.
+The @R{} distribution contains more than 1200 such files in the
[EMAIL PROTECTED]/library/@var{pkg}/man} directories of the @R{} source tree,
+where @var{pkg} stands for the standard packages that are included in
+the @R{} distribution.
As an example, let us look at the file
[EMAIL PROTECTED]/library/base/man/load.Rd} which documents the @R{} function
[EMAIL PROTECTED]/library/base/man/load.Rd}, which documents the @R{} function
@code{load}.
@quotation
@@ -2713,9 +2724,8 @@
@item [EMAIL PROTECTED]@[EMAIL PROTECTED]
@findex \details
-A detailed if possible precise description of the functionality
-provided, extending the basic information in the @code{\description}
-slot.
+A precise description of the functionality provided, extending the basic
+information in the @code{\description} slot.
@item [EMAIL PROTECTED]@[EMAIL PROTECTED]
@findex \value
@@ -2739,7 +2749,7 @@
@item [EMAIL PROTECTED]@}
@findex \note
-Use this for a special note you want to have pointed out.
+Special notes and comments.
For example, @file{pie.Rd} contains
@@ -2764,9 +2774,8 @@
@findex \seealso
Pointers to related @R{} objects, using @[EMAIL PROTECTED]@[EMAIL
PROTECTED]@}} to
refer to them (@code{\code} is the correct markup for @R{} object names,
-and @code{\link}
-produces hyperlinks in output formats which support this. @xref{Marking
-text}, and @ref{Cross-references}).
+and @code{\link} produces hyperlinks in output formats that support
+linking. @xref{Marking text}, and @ref{Cross-references}).
@findex \examples
@item [EMAIL PROTECTED]@[EMAIL PROTECTED]
@@ -2955,13 +2964,13 @@
methods.
@node Documenting packages, , Documenting S4 classes and methods, Rd format
[EMAIL PROTECTED] Documenting packages
+ @subsection Documenting packages
Packages may have an overview man page with an @code{\alias}
[EMAIL PROTECTED]@var{pkgname}-package}, e.g.@: @samp{utils-package} for the
[EMAIL PROTECTED] package, when @[EMAIL PROTECTED] will open that
-help page. If a topic named @[EMAIL PROTECTED] does not exist in
-another Rd file, it is helpful to use this as an additional
[EMAIL PROTECTED]@var{pkgname}-package} (e.g.@: @samp{utils-package} for the
[EMAIL PROTECTED] package) in which case @[EMAIL PROTECTED] will
+open that help page. If a topic named @[EMAIL PROTECTED] does not
+exist in another Rd file, it is helpful to use this as an additional
@code{\alias}.
Skeletons of documentation for a package can be generated using the
@@ -4771,7 +4780,6 @@
* Parsing R code from C::
* External pointers and weak references::
* Vector accessor functions::
-* Character encoding issues::
@end menu
@node Operating system access, Interface functions .C and .Fortran, System
and foreign language interfaces, System and foreign language interfaces
@@ -6909,10 +6917,9 @@
corresponding to the @code{i}'th element of the @code{STRSXP}
@code{theta}. Here, @code{STRING_ELT(theta, i)} accesses the
@code{i}'th element of the @code{STRSXP} @code{theta}. Macro
[EMAIL PROTECTED]()} extracts the actual character
[EMAIL PROTECTED]@pxref{Character encoding issues} for why this
-might not be what is required.} of it: it returns a pointer. We then
-install the name and use @code{findVar} to find its value.
[EMAIL PROTECTED]()} extracts the actual character representation of it: it
+returns a pointer. We then install the name and use @code{findVar} to
+find its value.
@example
@group
@@ -7145,7 +7152,7 @@
done more directly.
[EMAIL PROTECTED] Vector accessor functions, Character encoding issues,
External pointers and weak references, System and foreign language interfaces
[EMAIL PROTECTED] Vector accessor functions, , External pointers and weak
references, System and foreign language interfaces
@section Vector accessor functions
The vector accessors like @code{REAL} and @code{INTEGER} and
@@ -7169,21 +7176,6 @@
that your code compiled without @samp{USE_RINTERNALS} defined as this
provides a stricter test that the accessors have been used correctly.
[EMAIL PROTECTED] Character encoding issues, , Vector accessor functions,
System and foreign language interfaces
[EMAIL PROTECTED] Character encoding issues
-
[EMAIL PROTECTED] translateChar
-As from @R{} 2.5.0 @code{CHARSXP}s can be marked as coming from a known
-encoding (Latin-1 or UTF-8). This is mainly intended for human-readable
-output, and most packages can just treat such @code{CHARSXP}s as a
-whole. However, if they need to be interpreted as characters or output
-at C level then it would normally be correct to ensure that they are
-converted to the encoding of the currrent locale: this can be done by
-accessing the data in the @code{CHARSXP} by @code{translateChar} rather
-than by @code{CHAR}. If re-encoding is needed this allocates memory
-with @code{R_alloc} which thus persists to the end of the
[EMAIL PROTECTED]/@code{.External} call unless @code{vmaxset} is used.
-
@node The R API, Generic functions and methods, System and foreign language
interfaces, Top
@chapter The R @acronym{API}: entry points for C code
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
