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 <[email protected]>
> 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 <[email protected]>
>>> 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
>>>>>>> <[email protected]
>>>>>>> <mailto:[email protected]>> 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]]
>>>>>>>
>>>>>>> ______________________________________________
>>>>>>> [email protected] <javascript:;> mailing list
>>>>>>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>>>>>>>
>>> ______________________________________________
>>> [email protected] mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
______________________________________________
[email protected] mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
