[R-pkg-devel] Help needed to setting custom packages for R 3.1.2

Jennifer Bryan jenny at stat.ubc.ca
Tue Jul 21 20:08:39 CEST 2015


Sebastien: thanks for sharing the definitive solution!

To the people on this list with the power to edit "Writing R Extensions":

When a discussion here suggests a specific improvement, what is the best way for the community to propose a revision? So that knowledge gets transferred from this list to the relevant reference document and heads off future questions.

In this thread, we converged on cross-reference via \link[pkg:bar]{foo}. Section “2.5 Cross-references” in "Writing R Extensions” describes this type of cross-reference like so:

"These are rarely needed, perhaps to refer to not-yet-installed packages or in the normally undesirable event that more than one package offers help on a topic.”

But it can also be necessary when the author of package “pkg" has documented multiple things, including “foo”, in a single file, such as “bar”. This seems to be a sufficiently distinct and common scenario to merit a mention.

— Jenny

> On Jul 21, 2015, at 5:59 AM, sbihorel <Sebastien.Bihorel at cognigencorp.com> wrote:
> 
> Hi Jennifer,
> 
> Following your suggestions and after a couple of trial-and-error steps, I believe the syntax is the following:
> 
> \code{\link[name_of_package:name_of_Rd_file]{alias_or_text}}
> 
> For instance, to link to panel.abline or strip.custom from the lattice package, I used:
> 
> \code{\link[lattice:panel.functions]{panel.abline}}
> \code{\link[lattice:strip.default]{panel.custom}}
> 
> Using this notation I was able to make all warnings disappear upon installation of my package.
> 
> Typically, you can extract the name of the Rd file from the ? help page (upper left corner info). But this is not 100% reliable if the maintainer of the package is not consistent in the way (s)he documents the package.
> 
> Thanks a lot for your help.
> 
> Sebastien
> 
> 
> On 7/20/2015 5:45 PM, Jennifer Bryan wrote:
>> Hi Sebastien,
>> 
>> This note about Rd warnings reminded me that I recently had the same problem. So I recreated it and, I think, have found a solution.
>> 
>> I will explain in my specific example to be clear.
>> 
>> I need to link to the docs for the Token2.0 class from the httr package. First thing you try:
>> 
>> \code{\link[httr]{Token2.0}}
>> 
>> but then you get the warnings you describe upon installation. As in your case, the Token2.0 class doesn’t have it’s own .Rd file but is, rather, documented in the topic titled “Token-class”.
>> 
>> Next thing you try:
>> 
>> \code{\link[httr]{Token-class}}
>> 
>> which works, but I don’t like this display text — it doesn’t really make sense in the context of *my* documentation.
>> 
>> Finally you do this:
>> 
>> \code{\link[=Token-class]{Token2.0}}
>> 
>> to link to the correct topic but get the desired display text. However, I am no longer specifying that this topic is from the httr package, but it seems to work.
>> 
>> Maybe someone else can weigh in with more insight about the need / desirability of specifying the associated package.
>> 
>> — Jenny
>> 
>>> On Jul 20, 2015, at 2:05 PM, sbihorel <Sebastien.Bihorel at cognigencorp.com> wrote:
>>> 
>>> Hi,
>>> 
>>> Thanks to your suggestions and those of other responders, I was able to get rid of the warning messages returned during R CMD check.
>>> 
>>> However I am still confused by the .Rd file-related warnings I get when we install the packages. For instance:
>>> 
>>> Rd warning: /tmp/some/path/man/pkgC_function_009.Rd:21: missing file link "panel.abline"
>>> 
>>> I typed: \code{\link[lattice]{panel.abline}} on line 21 for the Rd file.
>>> 
>>> My NAMESPACE file includes:
>>> 
>>> importFrom(lattice,panel.abline)
>>> 
>>> Surprisingly, other cross-references to lattice functions also imported using importFrom do not generate warning upon installation.
>>> 
>>> When I consider the full list of function links that generate warnings, it looks like all of them are associated with alias rather than name tags in the target .Rd file (for instance, panel.abline is documented in a .Rd file with \name{panel.functions}).
>>> 
>>> The CRAN manual is not clear on this point. Is there a specific syntax to use to document this types of links?
>>> 
>>> Thank you again for your time
>>> 
>>> Sebastien
>>> 
>>> 
>>> On 7/15/2015 9:24 AM, Duncan Murdoch wrote:
>>>> On 15/07/2015 9:07 AM, sbihorel wrote:
>>>>> Hi,
>>>>> 
>>>>> I saw a few recent posts on topics related to mine (eg
>>>>> https://stat.ethz.ch/pipermail/r-package-devel/2015q3/000238.html). It
>>>>> looks like I need to import more packages in my NAMESPACE, correct?
>>>>> 
>>>>> However, I thought that imports would be recursive, ie imports would
>>>>> also get the info from dependent packages.
>>>> I haven't been following this thread, but the 2nd para above makes it
>>>> sound as though an explanation of the NAMESPACE directives would be helpful.
>>>> 
>>>> If you say
>>>> 
>>>>  importFrom(Hmisc, latex)
>>>> 
>>>> it acts as though you have made a copy of the Hmisc::latex function
>>>> within your package environment.  (It isn't exported, unless you ask to
>>>> export it.)
>>>> 
>>>> If you say
>>>> 
>>>>  import(Hmisc)
>>>> 
>>>> it acts as though you have made copies of every exported function from
>>>> Hmisc within your package environment.  This is why we recommend
>>>> importing only the functions you need; otherwise your package
>>>> environment gets bloated.
>>>> 
>>>> No recursive copies are made, unless Hmisc happens to import something
>>>> and re-exports it.
>>>> 
>>>> When I say "acts as though", I don't mean it literally makes copies; it
>>>> implements this in a more efficient way, basically only copying pointers
>>>> to those functions -- but from a user point of view, you shouldn't be
>>>> able to tell the difference, since you're not allowed to modify
>>>> Hmisc::latex.
>>>> 
>>>> Duncan Murdoch
>>>> 
>>>> 
>>>>> Sebastien
>>>>> 
>>>>> 
>>>>> On 7/13/2015 9:42 PM, sbihorel wrote:
>>>>>> Hi,
>>>>>> 
>>>>>> Sorry about the table. It looked good when displayed using a fixed
>>>>>> width font. Let me try to linearize it:
>>>>>> 
>>>>>>   * pkgA
>>>>>>       o DESCRIPTION:
>>>>>>           + Depends: methods, lattice, grid, gam
>>>>>>           + Imports: Hmisc, survival
>>>>>>       o NAMESPACE:
>>>>>>           + import: lattice, grid, gam, methods
>>>>>>           + importFrom: Hmisc (one function)
>>>>>>   * pkgB
>>>>>>       o DESCRIPTION:
>>>>>>           + Depends: pkgA
>>>>>>           + Imports: <nothing>
>>>>>>       o NAMESPACE:
>>>>>>           + import: pkgA
>>>>>>           + importFrom: <nothing
>>>>>>   * pkgC
>>>>>>       o DESCRIPTION:
>>>>>>           + Depends: methods, pkgB
>>>>>>           + Imports: <nothing>
>>>>>>       o NAMESPACE:
>>>>>>           + import: methods, pkgB
>>>>>>           + importFrom: <nothing
>>>>>> 
>>>>>> Regarding the export, pkgA, pkgB, and pkgC NAMESPACE files include:
>>>>>> exportPattern("^[^\\.]").
>>>>>> 
>>>>>> Sebastien
>>>>>> 
>>>>>> 
>>>>>> On 7/13/2015 5:36 PM, Seth Wenchel wrote:
>>>>>>> Are you exporting the functions from pkgB and pkgC? It's hard to tell
>>>>>>> from your table below. The easiest way is to add a comment before
>>>>>>> each of the functions in pkgB and pkgC that you want to expose to the
>>>>>>> users.
>>>>>>> 
>>>>>>> #' @export
>>>>>>> foo <- function(){...}
>>>>>>> 
>>>>>>> Then run roxygen::roxygenise() to build the NAMESPACE file.
>>>>>>> 
>>>>>>> HTH
>>>>>>> Seth
>>>>>>> 
>>>>>>> On Monday, July 13, 2015, sbihorel
>>>>>>> <Sebastien.Bihorel at cognigencorp.com
>>>>>>> <mailto:Sebastien.Bihorel at cognigencorp.com>> wrote:
>>>>>>> 
>>>>>>>     Hi,
>>>>>>> 
>>>>>>>     My group has recently upgraded from a fairly old R version (2.12)
>>>>>>>     to the
>>>>>>>     R version 3.1.2. In parallel to this upgrade, I am updating our
>>>>>>>     custom
>>>>>>>     packages to add functionality and also make them compliant to the
>>>>>>>     requirements of the new version of R. I would like to ask your
>>>>>>>     help with
>>>>>>>     respect to warning messages I get when I check and install the
>>>>>>>     packages.
>>>>>>>     I read the latest version of the manual on writing R extensions,
>>>>>>>     try to
>>>>>>>     apply the recommendations, but somehow I am not getting things right.
>>>>>>>     Hopefully, with your suggestions, I could setup my package
>>>>>>>     correctly to
>>>>>>>     make these messages stop.
>>>>>>> 
>>>>>>>     I apologize but, for confidentiality purpose, I will have to
>>>>>>>     partially
>>>>>>>     anonymize the information.
>>>>>>> 
>>>>>>>     So here is the situation: we have 2 custom packages (let's call them
>>>>>>>     pkgB and pkgC). The pkgB package depends on a 3rd package (let's
>>>>>>>     call it
>>>>>>>     pkgA) that is available on CRAN. The pkgC package depends on
>>>>>>>     pkgB, make
>>>>>>>     new function available,  and "overwrites" some of the functions
>>>>>>>     distributed as part of pkgA. The following table summarizes the
>>>>>>>     content
>>>>>>>     of the DESCRIPTION and NAMESPACE files of each of these packages.
>>>>>>> 
>>>>>>>     package    DESCRIPTION NAMESPACE
>>>>>>>                 Depends                       Imports
>>>>>>>     import                         importFrom
>>>>>>>     pkgA       methods, lattice, grid, gam   Hmisc, survival lattice,
>>>>>>>     grid,
>>>>>>>     gam, methods    Hmisc
>>>>>>>     pkgB       pkgA pkgA
>>>>>>>     pkgC       methods, pkgB methods, pkgB
>>>>>>> 
>>>>>>>     I do not get any warning when I build, check or install pkgB in our
>>>>>>>     linux openSuse environment.
>>>>>>> 
>>>>>>>     After successful building pkgC, I run R CMD check on my built for
>>>>>>>     pkgC
>>>>>>>     but I get a ton of messages under the "checking R code for possible
>>>>>>>     problems" section. These notes are related to actual calls to pkgA
>>>>>>>     functions (or to one of the function provided by its
>>>>>>>     dependencies). Here
>>>>>>>     is a subset for illustration and hopefully information.
>>>>>>> 
>>>>>>>     * checking R code for possible problems: NOTE
>>>>>>>     pkgC_function_001: no visible global function definition
>>>>>>>     for"pkgA_function_AAA"
>>>>>>>     pkgC_function_001: no visible global function definition
>>>>>>>     for"pkgA_function_AAB"
>>>>>>>     ...
>>>>>>>     pkgC_function_010: no visible global function definition for"xyplot"
>>>>>>>     pkgC_function_010: no visible global function definition
>>>>>>>     for"panel.xyplot"
>>>>>>>     pkgC_function_010: no visible global function definition
>>>>>>>     for"panel.abline"
>>>>>>>     pkgC_function_010: no visible global function definition
>>>>>>>     for"grid.polygon"
>>>>>>>     pkgC_function_010: no visible global function definition for"gpar"
>>>>>>>     ...
>>>>>>> 
>>>>>>>     Now when I try to install the pkgC_0.0.1.tar.gz package, I get the
>>>>>>>     following warnings about the content of my documentation Rd
>>>>>>>     files. The
>>>>>>>     Rd files of pkgC includes links to lattice, grid, or pkgA functions.
>>>>>>> 
>>>>>>>     *** installing help indices
>>>>>>>        converting help for package âkiwixposedevâ
>>>>>>>          finding HTML links ... done
>>>>>>>     pkgC_function_001                    html
>>>>>>>          pkgC_function_002                    html
>>>>>>>     ...
>>>>>>>     Rd warning: /tmp/some/path/man/pkgC_function_009.Rd:21: missing file
>>>>>>>     link "panel.abline"
>>>>>>>     ...
>>>>>>>     Rd warning: /tmp/some/path/man/pkgC_function_015.Rd:64: missing file
>>>>>>>     link "pkA_function_AAC"
>>>>>>>     ...
>>>>>>> 
>>>>>>>     I think I need to somehow modify the content of the DESCRIPTION and
>>>>>>>     NAMESPACE files for pkgC... but adding various combinations of
>>>>>>>     pkA and
>>>>>>>     its dependencies gave me others errors about redundancies and
>>>>>>>     multiple
>>>>>>>     loading of the same packages. So in short, I am kind of lost with the
>>>>>>>     new requirements of R 3.1.2 and would greatly appreciate any help or
>>>>>>>     suggestions
>>>>>>> 
>>>>>>>     Thank you in advance for your time.
>>>>>>> 
>>>>>>>     Sebastien Bihorel
>>>>>>> 
>>>>>>> 
>>>>>>>             [[alternative HTML version deleted]]
>>>>>>> 
>>>>>>>     ______________________________________________
>>>>>>>     R-package-devel at r-project.org <javascript:;> mailing list
>>>>>>>     https://stat.ethz.ch/mailman/listinfo/r-package-devel
>>>>>>> 
>>> ______________________________________________
>>> R-package-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-package-devel



More information about the R-package-devel mailing list