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

sbihorel Sebastien.Bihorel at cognigencorp.com
Tue Jul 21 14:59:19 CEST 2015


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