On 21/07/2015 2:08 PM, Jennifer Bryan wrote: > 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.
The best way is to use svn to get a copy of the manual from R-devel, make the change yourself and test it, and use "svn diff" to produce a patch file. Post a description of why you made the change and include a copy of the patch to the R-devel list. The source for WRE is in https://svn.r-project.org/R/trunk/doc/manual/R-exts.texi Nearly as good is to just grab the source and make the change, using some other diff method, and post about it on R-devel. But then the change should be very simple. Also good from your point of view is to convince someone with write access that the change is a good idea and get them to do all the work, but you'd be surprised how hard that is. Duncan Murdoch > 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.biho...@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.biho...@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.biho...@cognigencorp.com >>>>>>>> <mailto:sebastien.biho...@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@r-project.org <javascript:;> mailing list >>>>>>>> https://stat.ethz.ch/mailman/listinfo/r-package-devel >>>>>>>> >>>> ______________________________________________ >>>> R-package-devel@r-project.org mailing list >>>> https://stat.ethz.ch/mailman/listinfo/r-package-devel > ______________________________________________ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
