I believe that I have this straight now.
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). There's
nothing technical in these changes, and when unsure, I have tried to
avoid making changes that might affect meaning, so I don't think that
there's anything controversial here.
I have three more 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 approximate 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 here I was less confident that such edits
would be welcomed.
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 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,12 +276,12 @@
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
-optionally followed by a comparison operator (currently only @samp{>=}
+package names that this package depends on. Each package name in the list may
+optionally be 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
@@ -294,7 +294,7 @@
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
+and the packages listed 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,11 +329,11 @@
@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 must be attached in order 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
+All packages that are needed to run @code{R CMD check} successfully on
the package must be listed in one of @samp{Depends} or @samp{Suggests}
or @samp{Imports}.
@end itemize
@@ -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.
@@ -450,16 +450,16 @@
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
[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.} in a quoted character string (@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.
@findex .First.lib
@@ -492,14 +492,14 @@
- _ . + ! ' ( ) , ; @ = &}.} 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
-documented (@pxref{Package name spaces}).
+an example. 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
subdirectories named @file{unix} or @file{windows}.
@@ -526,7 +526,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 +588,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 +607,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 +644,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 containing only fields additional to
+the @file{DESCRIPTION} file of the bundle; for example:
@quotation
@cartouche
@@ -689,10 +689,11 @@
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
+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
[EMAIL PROTECTED] 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
@@ -772,8 +773,8 @@
@[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
---help} for details.
+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
from the official Autoconf Macro Archive, one can simply do
@@ -855,10 +856,10 @@
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
[EMAIL PROTECTED] itself, are stored on Unix-alikes in
+Some macros that are built whilst configuring the building of
[EMAIL PROTECTED] itself are stored on Unix-alikes in
@[EMAIL PROTECTED]/etc/Makeconf} and can be used in @file{Makevars}.
-These include
+These include:
@table @code
@item FLIBS
@@ -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,7 +1261,7 @@
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
+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
@@ -1300,7 +1301,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
@@ -1386,63 +1387,63 @@
@cindex vignettes
@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
+In addition to the help files in Rd format, @R{} packages may include
+documents in other formats. The standard location for these is the
+subdirectory @file{inst/doc} of a source package; 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 @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
-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.
+be in any 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 contain only @acronym{ASCII} letters, digits, minus, and
+underscore characters.
-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, then the vignette
+need not be compilable at install time, and the package author can use
+private @LaTeX{} extensions that may be available only on his machine.
[EMAIL PROTECTED] 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
-can be created from arbitrary source formats (plain @LaTeX{} files,
+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
-appear in the final package archive. Note that the @code{make} step is
-executed independently from the presence of any files in Sweave format.
+files and cleaning up afterwards, i.e., deletion of all files that
+should not appear in the final package archive. Note that the
[EMAIL PROTECTED] step is executed independently from the presence of any
+files in Sweave format.
It is no longer necessary to provide a @file{00Index.dcf} file in the
@file{inst/doc} directory---the corresponding information is generated
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 +1457,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 +1482,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 +1618,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 +1640,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 +1694,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,9 +1705,8 @@
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
-objects that need to be loaded to be specified in the @file{NAMESPACE}
-file. The directive
+The @file{NAMESPACE} file may contain one or more @code{useDynLib}
+directives specifying shared objects to be loaded. The directive
@findex useDynLib
@example
@@ -1725,16 +1726,17 @@
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
-these names. These can be used in the @code{.C}, @code{.Call},
+these names. These can then be used in the @code{.C}, @code{.Call},
@code{.Fortran} and @code{.External} calls in place of the
name of the routine and the @code{PACKAGE} argument.
For instance, we can call the routine @code{myRoutine} from R
@@ -1751,6 +1753,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,28 +1774,30 @@
useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)
@end example
[EMAIL PROTECTED]
We could then call that routine from @R{} using the command
@example
.Call(myRoutine_sym, x, y)
@end example
[EMAIL PROTECTED]
Symbols without explicit names are assigned to the @R{} variable with
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
+In some cases, it may be preferable to avoid creating @R{} variables
+to identify (some of) the package's native routines; e.g., when there are
+many such routines, a large number of which are unlikely to be used. In
+such cases, one can still perform the symbol resolution using the DLL,
+but this must be done each time the routine is called. Specifically,
+given a reference to the DLL as an @R{} 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 +1816,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 +1829,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 +1848,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 +1991,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 +2001,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 +2114,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,7 +2183,7 @@
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
+(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
@@ -2272,7 +2281,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 +2297,7 @@
@end example
@noindent
-and was replaced by
+which was replaced by
@example
if((length(nopkgs) > 0) && !missing(lib.loc)) @{
@@ -2316,8 +2325,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 +2340,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 +2410,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 +2515,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} represents the standard packages 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 +2722,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 +2747,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 +2772,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]
@@ -2957,12 +2964,12 @@
@node Documenting packages, , Documenting S4 classes and methods, Rd format
@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]
+Packages may have an overview man page containing
[EMAIL PROTECTED]@[EMAIL PROTECTED]@}} (e.g.@:
[EMAIL PROTECTED]@[EMAIL PROTECTED] in the case of the @pkg{utils} 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
function @code{promptPackage()}. If the @code{final = TRUE} argument
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
