Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Has the discussion about potential updates to Rd2HTML come to an end?
Should I be prepared to fix non-file package-anchored links in
(non-roxygen) packages I maintain, i.e., look up the help file structure
of the referenced packages?
I don't yet believe that R has really given up on supporting
developer-friendly, direct and simple links to
_topic_ rather than_file_
\link[rgeos]{gIntersection} -> \link[rgeos]{topo-bin-gIntersection}
\link[colorspace]{heat_hcl} -> \link[colorspace]{rainbow_hcl}
\link[RColorBrewer]{brewer.pal} -> \link[RColorBrewer]{ColorBrewer}
\link[gridExtra]{grid.arrange} -> link[gridExtra]{arrangeGrob}
\link[ggplot2]{geom_line} -> \link[ggplot2]{geom_path}
for pointing to other packages which are only in Suggests and thus not
necessarily installed at install-time of the referencing package.
Topic-based links to external functions are so much more intuitive. I do
not understand why there should be a penalty for clearly identifying the
target package as opposed to just writing \link{topic} and hoping that
the intended package will be found by the help system at run time.
Sebastian
Am 02.07.20 um 11:20 schrieb Gábor Csárdi:
> You can set the _R_CHECK_XREFS_MIND_SUSPECT_ANCHORS_=true env var and
> use R-devel.
>
> Alternatively, and you don't need R-devel for this, you can run R CMD
> --html INSTALL on your package, and then look for messages that
> contain "treated as a topic", e.g.
>
> curl_fdshtml
> Rd warning: /Users/gaborcsardi/works/processx/man/curl_fds.Rd:11: file
> link ‘multi_fdset’ in package ‘curl’ does not exist and so has been
> treated as a topic
>
> Gabor
>
>
> On Thu, Jul 2, 2020 at 10:06 AM Jan Gorecki wrote:
>>
>> Hi,
>> What is the recommended way to test for those issues locally?
>> If it is tested during cran submission, then seems reasonable to be enabled
>> just by --as-cran switch. Is it?
>> Thanks
>>
>> On Wed 17 Jun, 2020, 12:32 AM Wayne Oldford, wrote:
>>>
>>> Thank you!
>>>
>>> -----Original Message-----
>>> From: Gábor Csárdi
>>> Date: Tuesday, June 16, 2020 at 4:32 PM
>>> To: Wayne Oldford
>>> Cc: List r-package-devel
>>> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
>>> package-anchored link(s)
>>>
>>> This is how to look up the filename. The first "sp" is the topic name,
>>> the second is the package name.
>>>
>>> > help("sp", "sp")[[1]]
>>> [1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
>>>
>>> So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
>>>
>>> Gabor
>>>
>>> On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford
>>> wrote:
>>> >
>>> > Hi
>>> >
>>> > I got caught by this new test this week in trying to push an updated
>>> release of the loon package to CRAN.
>>> >
>>> > By following this thread, I corrected my cross-references to external
>>> packages but I got stymied by
>>> > the one I hoped to give to the "sp" package for Spatial data
>>> >
>>> > _
>>> >
>>> > Here is the history:
>>> >
>>> > I tried
>>> >\link[sp:sp]{sp}
>>> > which failed here:
>>> > Debian:
>>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
>>> > Status: 1 WARNING
>>> >
>>> >
>>> > That was meant to correct an earlier attempt (it did for other links
>>> to "scales" for example) where I had tried
>>> > \link[sp]{sp}
>>> > and failed here:
>>> > Debian:
>>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
>>> > Status: 1 WARNING
>>> >
>>> >
>>> > So to complete the possibilities as I understand them, I just now
>>> tried
>>> >\link{sp}
>>> > which, as might be expected, failed here:
>>> > Debian:
>>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
>>> > Status: 1 WARNING
>>> > As expected, error here was different: "Missing link" as
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On Linux you can use 'ltrace' to get a list of all the environment
variables that R looks up. E.g., do the following in 'script' so all the
output is stored in a file ('typescript') and later look around in it for
the getenv calls.
$ R-devel --debugger=ltrace --debugger-args="-f -e getenv"
...
[pid 25055] libR.so->getenv("R_HOME")
= "/home/R/R-devel/lib/R"
[pid 25055] libR.so->getenv("R_TRANSLATIONS")
= nil
[pid 25055] libR.so->getenv("R_PLATFORM")
= nil
...
> tools:::.check_packages(c("testFixup_0.1.tar.gz", "--as-cran"))[pid
25055] libR.so->getenv("_R_NS_LOAD_") =
nil
[pid 25055] libR.so->getenv("_R_CHECK_ELAPSED_TIMEOUT_")
= nil
[pid 25055] libR.so->getenv("R_CHECK_ENVIRON")
= nil
[pid 25055] libreadline.so.6->getenv("HOME")
= "/homes/bill"
[pid 25055] libR.so->getenv("_R_CHECK_TIMINGS_")
= nil
[pid 25055] libR.so->getenv("R_ENABLE_JIT")
= nil
[pid 25055] libR.so->getenv("R_HOME")
= "/home/R/R-devel/lib/R"
[pid 25055] libR.so->getenv("_R_CHECK_USE_INSTALL_LOG_")
= nil
[pid 25055] libR.so->getenv("_R_CHECK_SUBDIRS_NOCASE_")
= nil
[pid 25055] libR.so->getenv("_R_CHECK_ALL_NON_ISO_C_")
= nil
... hundreds more lines ...
> q("no")
Bill Dunlap
TIBCO Software
wdunlap tibco.com
On Thu, Jul 2, 2020 at 7:24 AM Jan Gorecki wrote:
> Thank you Gabor
>
> On Thu, Jul 2, 2020 at 10:20 AM Gábor Csárdi
> wrote:
> >
> > You can set the _R_CHECK_XREFS_MIND_SUSPECT_ANCHORS_=true env var and
> > use R-devel.
> >
> > Alternatively, and you don't need R-devel for this, you can run R CMD
> > --html INSTALL on your package, and then look for messages that
> > contain "treated as a topic", e.g.
> >
> > curl_fdshtml
> > Rd warning: /Users/gaborcsardi/works/processx/man/curl_fds.Rd:11: file
> > link ‘multi_fdset’ in package ‘curl’ does not exist and so has been
> > treated as a topic
> >
> > Gabor
> >
> >
> > On Thu, Jul 2, 2020 at 10:06 AM Jan Gorecki
> wrote:
> > >
> > > Hi,
> > > What is the recommended way to test for those issues locally?
> > > If it is tested during cran submission, then seems reasonable to be
> enabled just by --as-cran switch. Is it?
> > > Thanks
> > >
> > > On Wed 17 Jun, 2020, 12:32 AM Wayne Oldford,
> wrote:
> > >>
> > >> Thank you!
> > >>
> > >> -Original Message-
> > >> From: Gábor Csárdi
> > >> Date: Tuesday, June 16, 2020 at 4:32 PM
> > >> To: Wayne Oldford
> > >> Cc: List r-package-devel
> > >> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
> package-anchored link(s)
> > >>
> > >> This is how to look up the filename. The first "sp" is the topic
> name,
> > >> the second is the package name.
> > >>
> > >> > help("sp", "sp")[[1]]
> > >> [1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
> > >>
> > >> So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
> > >>
> > >> Gabor
> > >>
> > >> On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford <
> rwoldf...@uwaterloo.ca> wrote:
> > >> >
> > >> > Hi
> > >> >
> > >> > I got caught by this new test this week in trying to push an
> updated release of the loon package to CRAN.
> > >> >
> > >> > By following this thread, I corrected my cross-references to
> external packages but I got stymied by
> > >> > the one I hoped to give to the "sp" package for Spatial data
> > >> >
> > >> > _
> > >> >
> > >> > Here is the history:
> > >> >
> > >> > I tried
> > >> >\link[sp:sp]{sp}
> > >> > which failed here:
> > >> > Debian: <
> https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log
> >
> > >> > Status: 1 WARNING
> > >> >
> > >> >
> > >> > That was meant to correct an earlier attempt (it did for other
> links to "scales" for example) where I had tried
> >
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On 02/07/2020 10:41 a.m., Dr. Jens Oehlschlägel wrote: Thank you for the advice Duncan, But let's not get carried away here: we are talking about a *warning* that only arises if two packages are checked together that are never meant to be installed together. The new packages contain weeks of improvement-work, and I am not going to add back-and-forth-trick-work just to circumvent some warnings that arise only at the point of switching from old to new. That's a choice, but your package might face auto-rejection on CRAN. Asking CRAN to handle your update manually means extra work for them; if there's a simple way to handle it without that (and I've given you two to choose from), it seems kind of selfish not to use it. BTW, assuming you got the two packages on CRAN, it wouldn't be hard for a user to install the new bit without updating ff: just have both installed before your update, then ask to update bit. Since it doesn't depend on ff, it won't trigger an ff update. You can't expect R to know they were never meant to be installed together unless you record that fact in the dependencies in the DESCRIPTION file. Duncan Murdoch If there is a problem when checking the new packages together that's a different story and worth taking care about. I didn't find such problems. Kind regards Jens Gesendet: Donnerstag, 02. Juli 2020 um 15:23 Uhr Von: "Duncan Murdoch" An: "Dr. Jens Oehlschlägel" , r-package-devel@r-project.org Betreff: Re: Aw: Re: Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s) On 02/07/2020 7:49 a.m., Dr. Jens Oehlschlägel wrote: Duncan, One way is to make bit depend on a particular version of ff. That may cause a deadlock if both are being updated at once, but I think CRAN should be able to deal with it if they are informed of the issue. Exactly that I have done: I submitted all three packages bit/bit64/ff in version 4.0.2 and made them dependend on Version >= 4.0.0. And yes, the maintainers have been informed about the issue. I'm not sure that's what I meant, but I can't be sure, since I haven't seen your source. What I meant is a package dependency, i.e. the existing ff on CRAN is version 2.2-14.2 and it depends on bit without saying what version of bit is needed. The existing bit is 1.1-15.2 with no dependency on ff. So you can force the new ff to use the new bit by giving the version number, e.g. Depends: bit (>= 2.0) but it's not so obvious how to make the new bit depend on the new ff. There's no way to say that the dependency is only to a help page, and circular strong dependencies are messy, so I'd suggest you use one of the other options I offered: a dynamic link in the Rd file, or no link at all. Duncan Murdoch __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Thank you for the advice Duncan, But let's not get carried away here: we are talking about a *warning* that only arises if two packages are checked together that are never meant to be installed together. The new packages contain weeks of improvement-work, and I am not going to add back-and-forth-trick-work just to circumvent some warnings that arise only at the point of switching from old to new. If there is a problem when checking the new packages together that's a different story and worth taking care about. I didn't find such problems. Kind regards Jens > Gesendet: Donnerstag, 02. Juli 2020 um 15:23 Uhr > Von: "Duncan Murdoch" > An: "Dr. Jens Oehlschlägel" , > r-package-devel@r-project.org > Betreff: Re: Aw: Re: Re: [R-pkg-devel] check cross-references error: Non-file > package-anchored link(s) > > On 02/07/2020 7:49 a.m., Dr. Jens Oehlschlägel wrote: > > Duncan, > > > >> One way is to make bit depend on a particular version of ff. That may > >> cause a deadlock if both are being updated at once, but I think CRAN > >> should be able to deal with it if they are informed of the issue. > > > > Exactly that I have done: I submitted all three packages bit/bit64/ff in > > version 4.0.2 and made them dependend on Version >= 4.0.0. > > And yes, the maintainers have been informed about the issue. > > I'm not sure that's what I meant, but I can't be sure, since I haven't > seen your source. What I meant is a package dependency, i.e. the > existing ff on CRAN is version 2.2-14.2 and it depends on bit without > saying what version of bit is needed. The existing bit is 1.1-15.2 with > no dependency on ff. > > So you can force the new ff to use the new bit by giving the version > number, e.g. > > Depends: bit (>= 2.0) > > but it's not so obvious how to make the new bit depend on the new ff. > There's no way to say that the dependency is only to a help page, and > circular strong dependencies are messy, so I'd suggest you use one of > the other options I offered: a dynamic link in the Rd file, or no link > at all. > > Duncan Murdoch > __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Thank you Gabor
On Thu, Jul 2, 2020 at 10:20 AM Gábor Csárdi wrote:
>
> You can set the _R_CHECK_XREFS_MIND_SUSPECT_ANCHORS_=true env var and
> use R-devel.
>
> Alternatively, and you don't need R-devel for this, you can run R CMD
> --html INSTALL on your package, and then look for messages that
> contain "treated as a topic", e.g.
>
> curl_fdshtml
> Rd warning: /Users/gaborcsardi/works/processx/man/curl_fds.Rd:11: file
> link ‘multi_fdset’ in package ‘curl’ does not exist and so has been
> treated as a topic
>
> Gabor
>
>
> On Thu, Jul 2, 2020 at 10:06 AM Jan Gorecki wrote:
> >
> > Hi,
> > What is the recommended way to test for those issues locally?
> > If it is tested during cran submission, then seems reasonable to be enabled
> > just by --as-cran switch. Is it?
> > Thanks
> >
> > On Wed 17 Jun, 2020, 12:32 AM Wayne Oldford, wrote:
> >>
> >> Thank you!
> >>
> >> -Original Message-----
> >> From: Gábor Csárdi
> >> Date: Tuesday, June 16, 2020 at 4:32 PM
> >> To: Wayne Oldford
> >> Cc: List r-package-devel
> >> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
> >> package-anchored link(s)
> >>
> >> This is how to look up the filename. The first "sp" is the topic name,
> >> the second is the package name.
> >>
> >> > help("sp", "sp")[[1]]
> >> [1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
> >>
> >> So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
> >>
> >> Gabor
> >>
> >> On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford
> >> wrote:
> >> >
> >> > Hi
> >> >
> >> > I got caught by this new test this week in trying to push an updated
> >> release of the loon package to CRAN.
> >> >
> >> > By following this thread, I corrected my cross-references to
> >> external packages but I got stymied by
> >> > the one I hoped to give to the "sp" package for Spatial data
> >> >
> >> > _
> >> >
> >> > Here is the history:
> >> >
> >> > I tried
> >> >\link[sp:sp]{sp}
> >> > which failed here:
> >> > Debian:
> >> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
> >> > Status: 1 WARNING
> >> >
> >> >
> >> > That was meant to correct an earlier attempt (it did for other links
> >> to "scales" for example) where I had tried
> >> > \link[sp]{sp}
> >> > and failed here:
> >> > Debian:
> >> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
> >> > Status: 1 WARNING
> >> >
> >> >
> >> > So to complete the possibilities as I understand them, I just now
> >> tried
> >> >\link{sp}
> >> > which, as might be expected, failed here:
> >> > Debian:
> >> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
> >> > Status: 1 WARNING
> >> > As expected, error here was different: "Missing link" as opposed
> >> to "Non-file package-anchored link"
> >> >
> >> > _
> >> >
> >> >
> >> > I am not sure whether I have missed a subtlety in WRE or that the
> >> peculiar circumstance
> >> > where the package, the topic, and the file name are all identical
> >> (sp) is some weird boundary case.
> >> >
> >> > Without further advice, I think I am just going to remove the link
> >> to "sp".
> >> > It really is just a courtesy link to the package description for
> >> "sp".
> >> >
> >> > Thanks in advance for your thoughts.
> >> >
> >> > Wayne
> >> >
> >> >
> >> >
> >> >
> >> > -Original Message-
> >> > From: R-package-devel on
> >> behalf of Georgi Boshnakov
> >> > Date: Tuesda
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On 02/07/2020 7:49 a.m., Dr. Jens Oehlschlägel wrote: Duncan, One way is to make bit depend on a particular version of ff. That may cause a deadlock if both are being updated at once, but I think CRAN should be able to deal with it if they are informed of the issue. Exactly that I have done: I submitted all three packages bit/bit64/ff in version 4.0.2 and made them dependend on Version >= 4.0.0. And yes, the maintainers have been informed about the issue. I'm not sure that's what I meant, but I can't be sure, since I haven't seen your source. What I meant is a package dependency, i.e. the existing ff on CRAN is version 2.2-14.2 and it depends on bit without saying what version of bit is needed. The existing bit is 1.1-15.2 with no dependency on ff. So you can force the new ff to use the new bit by giving the version number, e.g. Depends: bit (>= 2.0) but it's not so obvious how to make the new bit depend on the new ff. There's no way to say that the dependency is only to a help page, and circular strong dependencies are messy, so I'd suggest you use one of the other options I offered: a dynamic link in the Rd file, or no link at all. Duncan Murdoch __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Duncan, > One way is to make bit depend on a particular version of ff. That may > cause a deadlock if both are being updated at once, but I think CRAN > should be able to deal with it if they are informed of the issue. Exactly that I have done: I submitted all three packages bit/bit64/ff in version 4.0.2 and made them dependend on Version >= 4.0.0. And yes, the maintainers have been informed about the issue. Best Jens __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
There are a few ways to deal with this, but waiting for ff to be updated
is probably easiest.
However, maybe ff can't be updated until bit is updated. Here are some
possibilities:
One way is to make bit depend on a particular version of ff. That may
cause a deadlock if both are being updated at once, but I think CRAN
should be able to deal with it if they are informed of the issue.
Another way is to use R code in the Rd file to select which link to use.
For example, instead of \link[ff]{clone.ff}, you could use
\Sexpr[results=rd,stage=render]{clonelink()}
where clonelink() is a function that generates either
"\link[ff]{clone.ff}" or "\link[ff:clone]{clone.ff}" depending on the
detected installed version of ff.
Another choice that is nearly as easy as doing nothing is to include no
link at all in this update, and make it a link again in the next update
when the new ff is available.
Duncan Murdoch
On 02/07/2020 6:47 a.m., Dr. Jens Oehlschlägel wrote:
Thanks Gabor and Duncan,
It's actually in ff/man/clone.rd, not clone.ff.rd. There is no
ff/man/clone.ff.rd file.
but there *is* clone.ff.rd in the >= 4.0.0 versions of the packages
bit/bit64/ff.
Hence the check warning is a false alarm resulting from checking bit 4.0.2
(GitHub.com/truecluster) against ff 2.2-14.2 (CRAN) instead of checking it
against the also submitted ff 4.0.2 (GitHub.com/truecluster).
So all I can and will do is waiting that CRAN maintainers install and check
again.
Best
Jens
Duncan Murdoch
Best regards
Jens
On 16.06.20 22:31, Gábor Csárdi wrote:
This is how to look up the filename. The first "sp" is the topic name,
the second is the package name.
help("sp", "sp")[[1]]
[1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
Gabor
On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford wrote:
Hi
I got caught by this new test this week in trying to push an updated release of
the loon package to CRAN.
By following this thread, I corrected my cross-references to external packages
but I got stymied by
the one I hoped to give to the "sp" package for Spatial data
_
Here is the history:
I tried
\link[sp:sp]{sp}
which failed here:
Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
Status: 1 WARNING
That was meant to correct an earlier attempt (it did for other links to
"scales" for example) where I had tried
\link[sp]{sp}
and failed here:
Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
Status: 1 WARNING
So to complete the possibilities as I understand them, I just now tried
\link{sp}
which, as might be expected, failed here:
Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
Status: 1 WARNING
As expected, error here was different: "Missing link" as opposed to "Non-file
package-anchored link"
_
I am not sure whether I have missed a subtlety in WRE or that the peculiar
circumstance
where the package, the topic, and the file name are all identical (sp) is some
weird boundary case.
Without further advice, I think I am just going to remove the link to "sp".
It really is just a courtesy link to the package description for "sp".
Thanks in advance for your thoughts.
Wayne
-Original Message-
From: R-package-devel on behalf of Georgi
Boshnakov
Date: Tuesday, June 16, 2020 at 9:27 AM
To: Gábor Csárdi , Duncan Murdoch
Cc: List r-package-devel
Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)
I think that the current behaviour is documented in WRE:
"...There are two other forms of optional argument specified as
\link[pkg]{foo} and
\link[pkg:bar]{foo} to link to the package pkg, to files foo.html and
bar.html respectively.
These are rarely needed, perhaps to refer to not-yet-installed packages
(but there the HTML
help system will resolve the link at run time) or in the normally
undesirable event that more
than one package offers help on a topic7 (in which case the present
package has precedence so
this is only needed to refer to other packages). They are currently only
used in HTML help
(and ignored for hyperlinks in LATEX conversions of help pages), and
link to the file rather
than the topic (since there is no way to know which topics are in which
files in an uninstalled
package) ... Because they have been frequently misused, the HTML help
system looks for topic foo in package pkg
if it does not find file foo.html."
Unless I am missing something, it seems that it would be relatively
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Yes, this is one consequence of the newly enforced check. Now you can
choose which version of the ff package you want to be compatible with.
In the GH version a manual file was renamed and this is now a breaking
change, so you cannot be compatible with both.
Gabor
On Thu, Jul 2, 2020 at 11:47 AM Dr. Jens Oehlschlägel
wrote:
>
> Thanks Gabor and Duncan,
>
> > It's actually in ff/man/clone.rd, not clone.ff.rd. There is no
> > ff/man/clone.ff.rd file.
>
> but there *is* clone.ff.rd in the >= 4.0.0 versions of the packages
> bit/bit64/ff.
>
> Hence the check warning is a false alarm resulting from checking bit 4.0.2
> (GitHub.com/truecluster) against ff 2.2-14.2 (CRAN) instead of checking it
> against the also submitted ff 4.0.2 (GitHub.com/truecluster).
>
> So all I can and will do is waiting that CRAN maintainers install and check
> again.
>
> Best
>
> Jens
>
>
>
> >
> > Duncan Murdoch
> >
> > >
> > > Best regards
> > >
> > > Jens
> > >
> > >
> > >
> > >
> > > On 16.06.20 22:31, Gábor Csárdi wrote:
> > >> This is how to look up the filename. The first "sp" is the topic name,
> > >> the second is the package name.
> > >>
> > >>> help("sp", "sp")[[1]]
> > >> [1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
> > >>
> > >> So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
> > >>
> > >> Gabor
> > >>
> > >> On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford
> > >> wrote:
> > >>>
> > >>> Hi
> > >>>
> > >>> I got caught by this new test this week in trying to push an updated
> > >>> release of the loon package to CRAN.
> > >>>
> > >>> By following this thread, I corrected my cross-references to external
> > >>> packages but I got stymied by
> > >>> the one I hoped to give to the "sp" package for Spatial data
> > >>>
> > >>> _
> > >>>
> > >>> Here is the history:
> > >>>
> > >>> I tried
> > >>> \link[sp:sp]{sp}
> > >>> which failed here:
> > >>> Debian:
> > >>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
> > >>> Status: 1 WARNING
> > >>>
> > >>>
> > >>> That was meant to correct an earlier attempt (it did for other links to
> > >>> "scales" for example) where I had tried
> > >>> \link[sp]{sp}
> > >>> and failed here:
> > >>> Debian:
> > >>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
> > >>> Status: 1 WARNING
> > >>>
> > >>>
> > >>> So to complete the possibilities as I understand them, I just now tried
> > >>> \link{sp}
> > >>> which, as might be expected, failed here:
> > >>> Debian:
> > >>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
> > >>> Status: 1 WARNING
> > >>> As expected, error here was different: "Missing link" as opposed to
> > >>> "Non-file package-anchored link"
> > >>>
> > >>> _
> > >>>
> > >>>
> > >>> I am not sure whether I have missed a subtlety in WRE or that the
> > >>> peculiar circumstance
> > >>> where the package, the topic, and the file name are all identical (sp)
> > >>> is some weird boundary case.
> > >>>
> > >>> Without further advice, I think I am just going to remove the link to
> > >>> "sp".
> > >>> It really is just a courtesy link to the package description for "sp".
> > >>>
> > >>> Thanks in advance for your thoughts.
> > >>>
> > >>> Wayne
> > >>>
> > >>>
> > >>>
> > >>>
> > >>> -Original Message-
> > >>> From: R-package-devel on behalf
> > >>> of Georgi Boshnakov
> > >>> Date: Tuesday, June 16, 2020 at 9:27 AM
> > >>> To: Gábor Csárdi , Duncan Murdoch
&
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Thanks Gabor and Duncan,
> It's actually in ff/man/clone.rd, not clone.ff.rd. There is no
> ff/man/clone.ff.rd file.
but there *is* clone.ff.rd in the >= 4.0.0 versions of the packages
bit/bit64/ff.
Hence the check warning is a false alarm resulting from checking bit 4.0.2
(GitHub.com/truecluster) against ff 2.2-14.2 (CRAN) instead of checking it
against the also submitted ff 4.0.2 (GitHub.com/truecluster).
So all I can and will do is waiting that CRAN maintainers install and check
again.
Best
Jens
>
> Duncan Murdoch
>
> >
> > Best regards
> >
> > Jens
> >
> >
> >
> >
> > On 16.06.20 22:31, Gábor Csárdi wrote:
> >> This is how to look up the filename. The first "sp" is the topic name,
> >> the second is the package name.
> >>
> >>> help("sp", "sp")[[1]]
> >> [1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
> >>
> >> So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
> >>
> >> Gabor
> >>
> >> On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford
> >> wrote:
> >>>
> >>> Hi
> >>>
> >>> I got caught by this new test this week in trying to push an updated
> >>> release of the loon package to CRAN.
> >>>
> >>> By following this thread, I corrected my cross-references to external
> >>> packages but I got stymied by
> >>> the one I hoped to give to the "sp" package for Spatial data
> >>>
> >>> _
> >>>
> >>> Here is the history:
> >>>
> >>> I tried
> >>> \link[sp:sp]{sp}
> >>> which failed here:
> >>> Debian:
> >>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
> >>> Status: 1 WARNING
> >>>
> >>>
> >>> That was meant to correct an earlier attempt (it did for other links to
> >>> "scales" for example) where I had tried
> >>> \link[sp]{sp}
> >>> and failed here:
> >>> Debian:
> >>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
> >>> Status: 1 WARNING
> >>>
> >>>
> >>> So to complete the possibilities as I understand them, I just now tried
> >>> \link{sp}
> >>> which, as might be expected, failed here:
> >>> Debian:
> >>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
> >>> Status: 1 WARNING
> >>> As expected, error here was different: "Missing link" as opposed to
> >>> "Non-file package-anchored link"
> >>>
> >>> _____
> >>>
> >>>
> >>> I am not sure whether I have missed a subtlety in WRE or that the
> >>> peculiar circumstance
> >>> where the package, the topic, and the file name are all identical (sp) is
> >>> some weird boundary case.
> >>>
> >>> Without further advice, I think I am just going to remove the link to
> >>> "sp".
> >>> It really is just a courtesy link to the package description for "sp".
> >>>
> >>> Thanks in advance for your thoughts.
> >>>
> >>> Wayne
> >>>
> >>>
> >>>
> >>>
> >>> -Original Message-
> >>> From: R-package-devel on behalf
> >>> of Georgi Boshnakov
> >>> Date: Tuesday, June 16, 2020 at 9:27 AM
> >>> To: Gábor Csárdi , Duncan Murdoch
> >>>
> >>> Cc: List r-package-devel
> >>> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
> >>> package-anchored link(s)
> >>>
> >>> I think that the current behaviour is documented in WRE:
> >>>
> >>> "...There are two other forms of optional argument specified as
> >>> \link[pkg]{foo} and
> >>> \link[pkg:bar]{foo} to link to the package pkg, to files foo.html
> >>> and bar.html respectively.
> >>> These are rarely needed, perhaps to refer to not-yet-installed
> >>> packages (but there the HTML
> >>> help system will resolve the link at run time) or in the normally
> >>> undesirable event that more
> >>
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
You can set the _R_CHECK_XREFS_MIND_SUSPECT_ANCHORS_=true env var and
use R-devel.
Alternatively, and you don't need R-devel for this, you can run R CMD
--html INSTALL on your package, and then look for messages that
contain "treated as a topic", e.g.
curl_fdshtml
Rd warning: /Users/gaborcsardi/works/processx/man/curl_fds.Rd:11: file
link ‘multi_fdset’ in package ‘curl’ does not exist and so has been
treated as a topic
Gabor
On Thu, Jul 2, 2020 at 10:06 AM Jan Gorecki wrote:
>
> Hi,
> What is the recommended way to test for those issues locally?
> If it is tested during cran submission, then seems reasonable to be enabled
> just by --as-cran switch. Is it?
> Thanks
>
> On Wed 17 Jun, 2020, 12:32 AM Wayne Oldford, wrote:
>>
>> Thank you!
>>
>> -Original Message-
>> From: Gábor Csárdi
>> Date: Tuesday, June 16, 2020 at 4:32 PM
>> To: Wayne Oldford
>> Cc: List r-package-devel
>> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
>> package-anchored link(s)
>>
>> This is how to look up the filename. The first "sp" is the topic name,
>> the second is the package name.
>>
>> > help("sp", "sp")[[1]]
>> [1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
>>
>> So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
>>
>> Gabor
>>
>> On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford
>> wrote:
>> >
>> > Hi
>> >
>> > I got caught by this new test this week in trying to push an updated
>> release of the loon package to CRAN.
>> >
>> > By following this thread, I corrected my cross-references to external
>> packages but I got stymied by
>> > the one I hoped to give to the "sp" package for Spatial data
>> >
>> > _
>> >
>> > Here is the history:
>> >
>> > I tried
>> >\link[sp:sp]{sp}
>> > which failed here:
>> > Debian:
>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
>> > Status: 1 WARNING
>> >
>> >
>> > That was meant to correct an earlier attempt (it did for other links
>> to "scales" for example) where I had tried
>> > \link[sp]{sp}
>> > and failed here:
>> > Debian:
>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
>> > Status: 1 WARNING
>> >
>> >
>> > So to complete the possibilities as I understand them, I just now
>> tried
>> >\link{sp}
>> > which, as might be expected, failed here:
>> > Debian:
>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
>> > Status: 1 WARNING
>> > As expected, error here was different: "Missing link" as opposed to
>> "Non-file package-anchored link"
>> >
>> > _
>> >
>> >
>> > I am not sure whether I have missed a subtlety in WRE or that the
>> peculiar circumstance
>> > where the package, the topic, and the file name are all identical (sp)
>> is some weird boundary case.
>> >
>> > Without further advice, I think I am just going to remove the link to
>> "sp".
>> > It really is just a courtesy link to the package description for "sp".
>> >
>> > Thanks in advance for your thoughts.
>> >
>> > Wayne
>> >
>> >
>> >
>> >
>> > -Original Message-
>> > From: R-package-devel on
>> behalf of Georgi Boshnakov
>> > Date: Tuesday, June 16, 2020 at 9:27 AM
>> > To: Gábor Csárdi , Duncan Murdoch
>>
>> > Cc: List r-package-devel
>> > Subject: Re: [R-pkg-devel] check cross-references error: Non-file
>> package-anchored link(s)
>> >
>> > I think that the current behaviour is documented in WRE:
>> >
>> > "...There are two other forms of optional argument specified as
>> \link[pkg]{foo} and
>> > \link[pkg:bar]{foo} to link to the package pkg, to files foo.html
>> and bar.html respectively.
>> > T
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Hi,
What is the recommended way to test for those issues locally?
If it is tested during cran submission, then seems reasonable to be enabled
just by --as-cran switch. Is it?
Thanks
On Wed 17 Jun, 2020, 12:32 AM Wayne Oldford, wrote:
> Thank you!
>
> -Original Message-
> From: Gábor Csárdi
> Date: Tuesday, June 16, 2020 at 4:32 PM
> To: Wayne Oldford
> Cc: List r-package-devel
> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
> package-anchored link(s)
>
> This is how to look up the filename. The first "sp" is the topic name,
> the second is the package name.
>
> > help("sp", "sp")[[1]]
> [1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
>
> So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
>
> Gabor
>
> On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford
> wrote:
> >
> > Hi
> >
> > I got caught by this new test this week in trying to push an updated
> release of the loon package to CRAN.
> >
> > By following this thread, I corrected my cross-references to
> external packages but I got stymied by
> > the one I hoped to give to the "sp" package for Spatial data
> >
> > _
> >
> > Here is the history:
> >
> > I tried
> >\link[sp:sp]{sp}
> > which failed here:
> > Debian: <
> https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log
> >
> > Status: 1 WARNING
> >
> >
> > That was meant to correct an earlier attempt (it did for other links
> to "scales" for example) where I had tried
> > \link[sp]{sp}
> > and failed here:
> > Debian: <
> https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log
> >
> > Status: 1 WARNING
> >
> >
> > So to complete the possibilities as I understand them, I just now
> tried
> >\link{sp}
> > which, as might be expected, failed here:
> > Debian: <
> https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log
> >
> > Status: 1 WARNING
> > As expected, error here was different: "Missing link" as opposed
> to "Non-file package-anchored link"
> >
> > _
> >
> >
> > I am not sure whether I have missed a subtlety in WRE or that the
> peculiar circumstance
> > where the package, the topic, and the file name are all identical
> (sp) is some weird boundary case.
> >
> > Without further advice, I think I am just going to remove the link
> to "sp".
> > It really is just a courtesy link to the package description for
> "sp".
> >
> > Thanks in advance for your thoughts.
> >
> > Wayne
> >
> >
> >
> >
> > -Original Message-
> > From: R-package-devel on
> behalf of Georgi Boshnakov
> > Date: Tuesday, June 16, 2020 at 9:27 AM
> > To: Gábor Csárdi , Duncan Murdoch <
> murdoch.dun...@gmail.com>
> > Cc: List r-package-devel
> > Subject: Re: [R-pkg-devel] check cross-references error: Non-file
> package-anchored link(s)
> >
> > I think that the current behaviour is documented in WRE:
> >
> > "...There are two other forms of optional argument specified as
> \link[pkg]{foo} and
> > \link[pkg:bar]{foo} to link to the package pkg, to files
> foo.html and bar.html respectively.
> > These are rarely needed, perhaps to refer to not-yet-installed
> packages (but there the HTML
> > help system will resolve the link at run time) or in the
> normally undesirable event that more
> > than one package offers help on a topic7 (in which case the
> present package has precedence so
> > this is only needed to refer to other packages). They are
> currently only used in HTML help
> > (and ignored for hyperlinks in LATEX conversions of help pages),
> and link to the file rather
> > than the topic (since there is no way to know which topics are
> in which files in an uninstalled
> > package) ... Because they have been frequently misused, the
> HTML help system looks for topic foo in package pkg
> > if it does not find file foo.html."
> >
> > Unless I am missing something,
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On 01/07/2020 1:46 p.m., Dr. Jens Oehlschlägel wrote:
Good evening,
My package bit 4.0.2 (https://github.com/truecluster/bit) is being
rejected by CRAN checks with warning:
>Check: Rd cross-references, Result: WARNING
> Non-file package-anchored link(s) in documentation object 'clone.Rd':
>'[ff]{clone.ff}'
>
> See section 'Cross-references' in the 'Writing R Extensions' manual.
although clone.ff is in clone.ff.rd as confirmed by
> help("clone.ff","ff")[[1]]
[1] "/home/mypc/R/x86_64-pc-linux-gnu-library/4.0/ff/help/clone.ff"
I asked the maintainers to explain what is wrong and what to do and got
no answer. Does someone here can help?
It's actually in ff/man/clone.rd, not clone.ff.rd. There is no
ff/man/clone.ff.rd file.
Duncan Murdoch
Best regards
Jens
On 16.06.20 22:31, Gábor Csárdi wrote:
This is how to look up the filename. The first "sp" is the topic name,
the second is the package name.
help("sp", "sp")[[1]]
[1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
Gabor
On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford wrote:
Hi
I got caught by this new test this week in trying to push an updated release of
the loon package to CRAN.
By following this thread, I corrected my cross-references to external packages
but I got stymied by
the one I hoped to give to the "sp" package for Spatial data
_
Here is the history:
I tried
\link[sp:sp]{sp}
which failed here:
Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
Status: 1 WARNING
That was meant to correct an earlier attempt (it did for other links to
"scales" for example) where I had tried
\link[sp]{sp}
and failed here:
Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
Status: 1 WARNING
So to complete the possibilities as I understand them, I just now tried
\link{sp}
which, as might be expected, failed here:
Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
Status: 1 WARNING
As expected, error here was different: "Missing link" as opposed to "Non-file
package-anchored link"
_
I am not sure whether I have missed a subtlety in WRE or that the peculiar
circumstance
where the package, the topic, and the file name are all identical (sp) is some
weird boundary case.
Without further advice, I think I am just going to remove the link to "sp".
It really is just a courtesy link to the package description for "sp".
Thanks in advance for your thoughts.
Wayne
-----Original Message-----
From: R-package-devel on behalf of Georgi
Boshnakov
Date: Tuesday, June 16, 2020 at 9:27 AM
To: Gábor Csárdi , Duncan Murdoch
Cc: List r-package-devel
Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)
I think that the current behaviour is documented in WRE:
"...There are two other forms of optional argument specified as
\link[pkg]{foo} and
\link[pkg:bar]{foo} to link to the package pkg, to files foo.html and
bar.html respectively.
These are rarely needed, perhaps to refer to not-yet-installed packages
(but there the HTML
help system will resolve the link at run time) or in the normally
undesirable event that more
than one package offers help on a topic7 (in which case the present
package has precedence so
this is only needed to refer to other packages). They are currently only
used in HTML help
(and ignored for hyperlinks in LATEX conversions of help pages), and link
to the file rather
than the topic (since there is no way to know which topics are in which
files in an uninstalled
package) ... Because they have been frequently misused, the HTML help
system looks for topic foo in package pkg
if it does not find file foo.html."
Unless I am missing something, it seems that it would be relatively
painless to reverse the logic of the current behaviour of the help system,
i.e. to start looking first for the topic and then for a file.
Georgi Boshnakov
-----Original Message-
From: R-package-devel On Behalf
Of Gábor Csárdi
Sent: 16 June 2020 13:44
To: Duncan Murdoch
Cc: List r-package-devel
Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)
On Mon, Jun 15, 2020 at 5:30 PM Duncan Murdoch
wrote:
>
> On 15/06/2020 12:05 p.m., Martin Maechler wrote:
> >>>>>> Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
> >
> > >
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Linking to the manual _file_ is now enforced on CRAN. Here is how to
get the file name:
> help("clone.ff", package = "ff")[[1]]
[1] "/Users/gaborcsardi/Library/R/4.0/library/ff/help/clone"
So in this case you need to link to 'clone'.
Btw. since you already use roxygen2, you could also turn on markdown
support, and then [ff::clone.ff()] automatically creates the right
links in the latest version of roxygen2.
Gabor
On Wed, Jul 1, 2020 at 6:46 PM Dr. Jens Oehlschlägel
wrote:
>
> Good evening,
>
> My package bit 4.0.2 (https://github.com/truecluster/bit) is being
> rejected by CRAN checks with warning:
>
>
> >Check: Rd cross-references, Result: WARNING
> > Non-file package-anchored link(s) in documentation object 'clone.Rd':
> >'[ff]{clone.ff}'
> >
> > See section 'Cross-references' in the 'Writing R Extensions' manual.
>
> although clone.ff is in clone.ff.rd as confirmed by
>
> > help("clone.ff","ff")[[1]]
> [1] "/home/mypc/R/x86_64-pc-linux-gnu-library/4.0/ff/help/clone.ff"
>
> I asked the maintainers to explain what is wrong and what to do and got
> no answer. Does someone here can help?
>
> Best regards
>
> Jens
>
>
>
>
> On 16.06.20 22:31, Gábor Csárdi wrote:
> > This is how to look up the filename. The first "sp" is the topic name,
> > the second is the package name.
> >
> >> help("sp", "sp")[[1]]
> > [1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
> >
> > So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
> >
> > Gabor
> >
> > On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford
> > wrote:
> >>
> >> Hi
> >>
> >> I got caught by this new test this week in trying to push an updated
> >> release of the loon package to CRAN.
> >>
> >> By following this thread, I corrected my cross-references to external
> >> packages but I got stymied by
> >> the one I hoped to give to the "sp" package for Spatial data
> >>
> >> _
> >>
> >> Here is the history:
> >>
> >> I tried
> >> \link[sp:sp]{sp}
> >> which failed here:
> >> Debian:
> >> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
> >> Status: 1 WARNING
> >>
> >>
> >> That was meant to correct an earlier attempt (it did for other links to
> >> "scales" for example) where I had tried
> >>\link[sp]{sp}
> >> and failed here:
> >> Debian:
> >> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
> >> Status: 1 WARNING
> >>
> >>
> >> So to complete the possibilities as I understand them, I just now tried
> >> \link{sp}
> >> which, as might be expected, failed here:
> >> Debian:
> >> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
> >> Status: 1 WARNING
> >> As expected, error here was different: "Missing link" as opposed to
> >> "Non-file package-anchored link"
> >>
> >> _____
> >>
> >>
> >> I am not sure whether I have missed a subtlety in WRE or that the peculiar
> >> circumstance
> >> where the package, the topic, and the file name are all identical (sp) is
> >> some weird boundary case.
> >>
> >> Without further advice, I think I am just going to remove the link to "sp".
> >> It really is just a courtesy link to the package description for "sp".
> >>
> >> Thanks in advance for your thoughts.
> >>
> >> Wayne
> >>
> >>
> >>
> >>
> >> -Original Message-
> >> From: R-package-devel on behalf of
> >> Georgi Boshnakov
> >> Date: Tuesday, June 16, 2020 at 9:27 AM
> >> To: Gábor Csárdi , Duncan Murdoch
> >>
> >> Cc: List r-package-devel
> >> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
> >> package-anchored link(s)
> >>
> >> I think that the current behaviour is documented in WRE:
> >>
> >> "...There are two other forms of optional argument specified as
> >> \link[pkg]{foo} and
> >> \link[pkg:bar]{foo} to link to the package pkg, to files foo.html a
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Good evening,
My package bit 4.0.2 (https://github.com/truecluster/bit) is being
rejected by CRAN checks with warning:
>Check: Rd cross-references, Result: WARNING
> Non-file package-anchored link(s) in documentation object 'clone.Rd':
>'[ff]{clone.ff}'
>
> See section 'Cross-references' in the 'Writing R Extensions' manual.
although clone.ff is in clone.ff.rd as confirmed by
> help("clone.ff","ff")[[1]]
[1] "/home/mypc/R/x86_64-pc-linux-gnu-library/4.0/ff/help/clone.ff"
I asked the maintainers to explain what is wrong and what to do and got
no answer. Does someone here can help?
Best regards
Jens
On 16.06.20 22:31, Gábor Csárdi wrote:
> This is how to look up the filename. The first "sp" is the topic name,
> the second is the package name.
>
>> help("sp", "sp")[[1]]
> [1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
>
> So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
>
> Gabor
>
> On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford wrote:
>>
>> Hi
>>
>> I got caught by this new test this week in trying to push an updated release
>> of the loon package to CRAN.
>>
>> By following this thread, I corrected my cross-references to external
>> packages but I got stymied by
>> the one I hoped to give to the "sp" package for Spatial data
>>
>> _
>>
>> Here is the history:
>>
>> I tried
>> \link[sp:sp]{sp}
>> which failed here:
>> Debian:
>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
>> Status: 1 WARNING
>>
>>
>> That was meant to correct an earlier attempt (it did for other links to
>> "scales" for example) where I had tried
>>\link[sp]{sp}
>> and failed here:
>> Debian:
>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
>> Status: 1 WARNING
>>
>>
>> So to complete the possibilities as I understand them, I just now tried
>> \link{sp}
>> which, as might be expected, failed here:
>> Debian:
>> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
>> Status: 1 WARNING
>> As expected, error here was different: "Missing link" as opposed to
>> "Non-file package-anchored link"
>>
>> _
>>
>>
>> I am not sure whether I have missed a subtlety in WRE or that the peculiar
>> circumstance
>> where the package, the topic, and the file name are all identical (sp) is
>> some weird boundary case.
>>
>> Without further advice, I think I am just going to remove the link to "sp".
>> It really is just a courtesy link to the package description for "sp".
>>
>> Thanks in advance for your thoughts.
>>
>> Wayne
>>
>>
>>
>>
>> -Original Message-
>> From: R-package-devel on behalf of
>> Georgi Boshnakov
>> Date: Tuesday, June 16, 2020 at 9:27 AM
>> To: Gábor Csárdi , Duncan Murdoch
>>
>> Cc: List r-package-devel
>> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
>> package-anchored link(s)
>>
>> I think that the current behaviour is documented in WRE:
>>
>> "...There are two other forms of optional argument specified as
>> \link[pkg]{foo} and
>> \link[pkg:bar]{foo} to link to the package pkg, to files foo.html and
>> bar.html respectively.
>> These are rarely needed, perhaps to refer to not-yet-installed packages
>> (but there the HTML
>> help system will resolve the link at run time) or in the normally
>> undesirable event that more
>> than one package offers help on a topic7 (in which case the present
>> package has precedence so
>> this is only needed to refer to other packages). They are currently
>> only used in HTML help
>> (and ignored for hyperlinks in LATEX conversions of help pages), and
>> link to the file rather
>> than the topic (since there is no way to know which topics are in which
>> files in an uninstalled
>> package) ... Because they have been frequently misused, the HTML help
>> system looks for topic foo in package pkg
>> if it does not find file foo.html."
>>
>> Unless I am missing something, it seems that it would be relatively
>> painless to reverse the logic of the current behav
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Thank you!
-Original Message-
From: Gábor Csárdi
Date: Tuesday, June 16, 2020 at 4:32 PM
To: Wayne Oldford
Cc: List r-package-devel
Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)
This is how to look up the filename. The first "sp" is the topic name,
the second is the package name.
> help("sp", "sp")[[1]]
[1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
Gabor
On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford
wrote:
>
> Hi
>
> I got caught by this new test this week in trying to push an updated
release of the loon package to CRAN.
>
> By following this thread, I corrected my cross-references to external
packages but I got stymied by
> the one I hoped to give to the "sp" package for Spatial data
>
> _
>
> Here is the history:
>
> I tried
>\link[sp:sp]{sp}
> which failed here:
> Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
> Status: 1 WARNING
>
>
> That was meant to correct an earlier attempt (it did for other links to
"scales" for example) where I had tried
> \link[sp]{sp}
> and failed here:
> Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
> Status: 1 WARNING
>
>
> So to complete the possibilities as I understand them, I just now tried
>\link{sp}
> which, as might be expected, failed here:
> Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
> Status: 1 WARNING
> As expected, error here was different: "Missing link" as opposed to
"Non-file package-anchored link"
>
> _
>
>
> I am not sure whether I have missed a subtlety in WRE or that the
peculiar circumstance
> where the package, the topic, and the file name are all identical (sp) is
some weird boundary case.
>
> Without further advice, I think I am just going to remove the link to
"sp".
> It really is just a courtesy link to the package description for "sp".
>
> Thanks in advance for your thoughts.
>
> Wayne
>
>
>
>
> -Original Message-----
> From: R-package-devel on behalf
of Georgi Boshnakov
> Date: Tuesday, June 16, 2020 at 9:27 AM
> To: Gábor Csárdi , Duncan Murdoch
> Cc: List r-package-devel
> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)
>
> I think that the current behaviour is documented in WRE:
>
> "...There are two other forms of optional argument specified as
\link[pkg]{foo} and
> \link[pkg:bar]{foo} to link to the package pkg, to files foo.html and
bar.html respectively.
> These are rarely needed, perhaps to refer to not-yet-installed
packages (but there the HTML
> help system will resolve the link at run time) or in the normally
undesirable event that more
> than one package offers help on a topic7 (in which case the present
package has precedence so
> this is only needed to refer to other packages). They are currently
only used in HTML help
> (and ignored for hyperlinks in LATEX conversions of help pages), and
link to the file rather
> than the topic (since there is no way to know which topics are in
which files in an uninstalled
> package) ... Because they have been frequently misused, the HTML
help system looks for topic foo in package pkg
> if it does not find file foo.html."
>
> Unless I am missing something, it seems that it would be relatively
painless to reverse the logic of the current behaviour of the help system,
> i.e. to start looking first for the topic and then for a file.
>
> Georgi Boshnakov
>
> -Original Message-
> From: R-package-devel On
Behalf Of Gábor Csárdi
> Sent: 16 June 2020 13:44
> To: Duncan Murdoch
> Cc: List r-package-devel
> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)
>
> On Mon, Jun 15, 2020 at 5:30 PM Duncan Murdoch
wrote:
> >
> > On 15/06/2020 12:05 p.m., Martin Maechler wrote:
> > >>>>>> Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
&g
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
This is how to look up the filename. The first "sp" is the topic name,
the second is the package name.
> help("sp", "sp")[[1]]
[1] "C:/Users/csard/R/win-library/4.0/sp/help/00sp"
So you need to link to the "00sp.Rd" file: \link[sp:00sp]{sp}
Gabor
On Tue, Jun 16, 2020 at 9:09 PM Wayne Oldford wrote:
>
> Hi
>
> I got caught by this new test this week in trying to push an updated release
> of the loon package to CRAN.
>
> By following this thread, I corrected my cross-references to external
> packages but I got stymied by
> the one I hoped to give to the "sp" package for Spatial data
>
> _
>
> Here is the history:
>
> I tried
>\link[sp:sp]{sp}
> which failed here:
> Debian:
> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
> Status: 1 WARNING
>
>
> That was meant to correct an earlier attempt (it did for other links to
> "scales" for example) where I had tried
> \link[sp]{sp}
> and failed here:
> Debian:
> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
> Status: 1 WARNING
>
>
> So to complete the possibilities as I understand them, I just now tried
>\link{sp}
> which, as might be expected, failed here:
> Debian:
> <https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
> Status: 1 WARNING
> As expected, error here was different: "Missing link" as opposed to
> "Non-file package-anchored link"
>
> _
>
>
> I am not sure whether I have missed a subtlety in WRE or that the peculiar
> circumstance
> where the package, the topic, and the file name are all identical (sp) is
> some weird boundary case.
>
> Without further advice, I think I am just going to remove the link to "sp".
> It really is just a courtesy link to the package description for "sp".
>
> Thanks in advance for your thoughts.
>
> Wayne
>
>
>
>
> -Original Message-
> From: R-package-devel on behalf of
> Georgi Boshnakov
> Date: Tuesday, June 16, 2020 at 9:27 AM
> To: Gábor Csárdi , Duncan Murdoch
>
> Cc: List r-package-devel
> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
> package-anchored link(s)
>
> I think that the current behaviour is documented in WRE:
>
> "...There are two other forms of optional argument specified as
> \link[pkg]{foo} and
> \link[pkg:bar]{foo} to link to the package pkg, to files foo.html and
> bar.html respectively.
> These are rarely needed, perhaps to refer to not-yet-installed packages
> (but there the HTML
> help system will resolve the link at run time) or in the normally
> undesirable event that more
> than one package offers help on a topic7 (in which case the present
> package has precedence so
> this is only needed to refer to other packages). They are currently only
> used in HTML help
> (and ignored for hyperlinks in LATEX conversions of help pages), and link
> to the file rather
> than the topic (since there is no way to know which topics are in which
> files in an uninstalled
> package) ... Because they have been frequently misused, the HTML help
> system looks for topic foo in package pkg
> if it does not find file foo.html."
>
> Unless I am missing something, it seems that it would be relatively
> painless to reverse the logic of the current behaviour of the help system,
> i.e. to start looking first for the topic and then for a file.
>
> Georgi Boshnakov
>
> -Original Message-
> From: R-package-devel On Behalf
> Of Gábor Csárdi
> Sent: 16 June 2020 13:44
> To: Duncan Murdoch
> Cc: List r-package-devel
> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
> package-anchored link(s)
>
> On Mon, Jun 15, 2020 at 5:30 PM Duncan Murdoch
> wrote:
> >
> > On 15/06/2020 12:05 p.m., Martin Maechler wrote:
> > >>>>>> Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
> > >
> > > > I agree with almost everything you wrote, except one thing:
> this isn't
> > > > newly enforced, it has been enforced since the help system
> began. What
> > > > I think is new is that there are now tests for it. Previously
> those
> > > > links just wouldn't work.
> > >
> > > > Duncan Murdoch
> > >
> > > Yes
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Hi
I got caught by this new test this week in trying to push an updated release of
the loon package to CRAN.
By following this thread, I corrected my cross-references to external packages
but I got stymied by
the one I hoped to give to the "sp" package for Spatial data
_
Here is the history:
I tried
\link[sp:sp]{sp}
which failed here:
Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_162128/Debian/00check.log>
Status: 1 WARNING
That was meant to correct an earlier attempt (it did for other links to
"scales" for example) where I had tried
\link[sp]{sp}
and failed here:
Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200615_213749/Debian/00check.log>
Status: 1 WARNING
So to complete the possibilities as I understand them, I just now tried
\link{sp}
which, as might be expected, failed here:
Debian:
<https://win-builder.r-project.org/incoming_pretest/loon_1.3.1_20200616_213921/Debian/00check.log>
Status: 1 WARNING
As expected, error here was different: "Missing link" as opposed to
"Non-file package-anchored link"
_
I am not sure whether I have missed a subtlety in WRE or that the peculiar
circumstance
where the package, the topic, and the file name are all identical (sp) is some
weird boundary case.
Without further advice, I think I am just going to remove the link to "sp".
It really is just a courtesy link to the package description for "sp".
Thanks in advance for your thoughts.
Wayne
-Original Message-
From: R-package-devel on behalf of
Georgi Boshnakov
Date: Tuesday, June 16, 2020 at 9:27 AM
To: Gábor Csárdi , Duncan Murdoch
Cc: List r-package-devel
Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)
I think that the current behaviour is documented in WRE:
"...There are two other forms of optional argument specified as
\link[pkg]{foo} and
\link[pkg:bar]{foo} to link to the package pkg, to files foo.html and
bar.html respectively.
These are rarely needed, perhaps to refer to not-yet-installed packages
(but there the HTML
help system will resolve the link at run time) or in the normally
undesirable event that more
than one package offers help on a topic7 (in which case the present package
has precedence so
this is only needed to refer to other packages). They are currently only
used in HTML help
(and ignored for hyperlinks in LATEX conversions of help pages), and link
to the file rather
than the topic (since there is no way to know which topics are in which
files in an uninstalled
package) ... Because they have been frequently misused, the HTML help
system looks for topic foo in package pkg
if it does not find file foo.html."
Unless I am missing something, it seems that it would be relatively
painless to reverse the logic of the current behaviour of the help system,
i.e. to start looking first for the topic and then for a file.
Georgi Boshnakov
-Original Message-
From: R-package-devel On Behalf Of
Gábor Csárdi
Sent: 16 June 2020 13:44
To: Duncan Murdoch
Cc: List r-package-devel
Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)
On Mon, Jun 15, 2020 at 5:30 PM Duncan Murdoch
wrote:
>
> On 15/06/2020 12:05 p.m., Martin Maechler wrote:
> >>>>>> Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
> >
> > > I agree with almost everything you wrote, except one thing:
this isn't
> > > newly enforced, it has been enforced since the help system
began. What
> > > I think is new is that there are now tests for it. Previously
those
> > > links just wouldn't work.
> >
> > > Duncan Murdoch
> >
> > Yes, to all... including Duncan's agreement with Gábor.
> >
> > Also, Duncan M earlier did mention that he had wanted to
> > *change* the link-to-file behavior for these cases (when he wrote
> > most of the Rd2html source code) but somehow did not get it.
>
> Actually, I don't think I pushed for this change at the time (or at
> least I didn't push much). I just wish now that I had, because I
> think it will be harder to do it now than it would have been then.
>
> Duncan
I am not entirely sure, but maybe just documenting the current behaviour
and undoing 78674 could work. With some tweaks? E.g.
* updating R-exts to say that \link[pkg:topic]{text} will link to
`topic.html` in `pkg` first (for historical reasons), and falls back to
searching for `topic` in `pkg` at render time.
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
I think that the current behaviour is documented in WRE:
"...There are two other forms of optional argument specified as \link[pkg]{foo}
and
\link[pkg:bar]{foo} to link to the package pkg, to files foo.html and bar.html
respectively.
These are rarely needed, perhaps to refer to not-yet-installed packages (but
there the HTML
help system will resolve the link at run time) or in the normally undesirable
event that more
than one package offers help on a topic7 (in which case the present package has
precedence so
this is only needed to refer to other packages). They are currently only used
in HTML help
(and ignored for hyperlinks in LATEX conversions of help pages), and link to
the file rather
than the topic (since there is no way to know which topics are in which files
in an uninstalled
package) ... Because they have been frequently misused, the HTML help system
looks for topic foo in package pkg
if it does not find file foo.html."
Unless I am missing something, it seems that it would be relatively painless to
reverse the logic of the current behaviour of the help system,
i.e. to start looking first for the topic and then for a file.
Georgi Boshnakov
-Original Message-
From: R-package-devel On Behalf Of
Gábor Csárdi
Sent: 16 June 2020 13:44
To: Duncan Murdoch
Cc: List r-package-devel
Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)
On Mon, Jun 15, 2020 at 5:30 PM Duncan Murdoch wrote:
>
> On 15/06/2020 12:05 p.m., Martin Maechler wrote:
> >>>>>> Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
> >
> > > I agree with almost everything you wrote, except one thing: this
> > isn't
> > > newly enforced, it has been enforced since the help system began.
> > What
> > > I think is new is that there are now tests for it. Previously those
> > > links just wouldn't work.
> >
> > > Duncan Murdoch
> >
> > Yes, to all... including Duncan's agreement with Gábor.
> >
> > Also, Duncan M earlier did mention that he had wanted to
> > *change* the link-to-file behavior for these cases (when he wrote
> > most of the Rd2html source code) but somehow did not get it.
>
> Actually, I don't think I pushed for this change at the time (or at
> least I didn't push much). I just wish now that I had, because I
> think it will be harder to do it now than it would have been then.
>
> Duncan
I am not entirely sure, but maybe just documenting the current behaviour and
undoing 78674 could work. With some tweaks? E.g.
* updating R-exts to say that \link[pkg:topic]{text} will link to `topic.html`
in `pkg` first (for historical reasons), and falls back to searching for
`topic` in `pkg` at render time.
* updating Rd2HTML to look for the topic and use it in the link, instead of
throwing a warning, in it cannot find `topic.html`
* removing the `R CMD check` warning for non-file links, that was added in
78674 :)
Is there anything else?
Gabor
[...]
__
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
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On Mon, Jun 15, 2020 at 5:30 PM Duncan Murdoch wrote:
>
> On 15/06/2020 12:05 p.m., Martin Maechler wrote:
> >> Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
> >
> > > I agree with almost everything you wrote, except one thing: this
> > isn't
> > > newly enforced, it has been enforced since the help system began.
> > What
> > > I think is new is that there are now tests for it. Previously those
> > > links just wouldn't work.
> >
> > > Duncan Murdoch
> >
> > Yes, to all... including Duncan's agreement with Gábor.
> >
> > Also, Duncan M earlier did mention that he had wanted to
> > *change* the link-to-file behavior for these cases (when he
> > wrote most of the Rd2html source code) but somehow did not get it.
>
> Actually, I don't think I pushed for this change at the time (or at
> least I didn't push much). I just wish now that I had, because I think
> it will be harder to do it now than it would have been then.
>
> Duncan
I am not entirely sure, but maybe just documenting the current
behaviour and undoing 78674 could work. With some tweaks? E.g.
* updating R-exts to say that \link[pkg:topic]{text} will link to
`topic.html` in `pkg` first (for historical reasons), and falls back
to searching for `topic` in `pkg` at render time.
* updating Rd2HTML to look for the topic and use it in the link,
instead of throwing a warning, in it cannot find `topic.html`
* removing the `R CMD check` warning for non-file links, that was
added in 78674 :)
Is there anything else?
Gabor
[...]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Thank you so much!
David
On Tue, 16 Jun 2020 at 08:36, Georgi Boshnakov <
georgi.boshna...@manchester.ac.uk> wrote:
> The Rd file is mplus.Rd, so
> ‘[lubridate:mplus]{lubridate::add_with_rollback()}’ would do.
>
> Georgi Boshnakov
>
> -Original Message-
> From: R-package-devel On Behalf
> Of David Hugh-Jones
> Sent: 16 June 2020 07:51
> To: Duncan Murdoch
> Cc: List r-package-devel
> Subject: Re: [R-pkg-devel] check cross-references error: Non-file
> package-anchored link(s)
>
> On this note, I just got
>
> Non-file package-anchored link(s) in documentation object
> 'brk_width-for-datetime.Rd':
> ‘[lubridate:%m+%]{lubridate::add_with_rollback()}’
>
> The correct filename appears to be %m+% in the lubridate help. Can anyone
> tell me the right way to format this? I would work it out myself, but the
> check didn't cause problems on the r-devel systems I tested with, so I'd be
> testing blind.
>
> Cheers,
> David
>
>
> On Mon, 15 Jun 2020 at 17:30, Duncan Murdoch
> wrote:
>
> > On 15/06/2020 12:05 p.m., Martin Maechler wrote:
> > >>>>>> Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
> > >
> > > > I agree with almost everything you wrote, except one thing:
> > > this
> > isn't
> > > > newly enforced, it has been enforced since the help system
> > began. What
> > > > I think is new is that there are now tests for it.
> > > Previously
> > those
> > > > links just wouldn't work.
> > >
> > > > Duncan Murdoch
> > >
> > > Yes, to all... including Duncan's agreement with Gábor.
> > >
> > > Also, Duncan M earlier did mention that he had wanted to
> > > *change* the link-to-file behavior for these cases (when he wrote
> > > most of the Rd2html source code) but somehow did not get it.
> >
> > Actually, I don't think I pushed for this change at the time (or at
> > least I didn't push much). I just wish now that I had, because I
> > think it will be harder to do it now than it would have been then.
> >
> > Duncan
> >
> > >
> > > And that's why we had partial workarounds (as the dynamic server
> > > still finding the links under some circumstances).
> > >
> > > My personal opinions was also that "we" (the R community; i.e.,
> > > people providing good patches to the R sources / collaborating with
> > > R core / ...) should rather work to fix the current
> > > design/implementation "infelicity" than the current checks starting
> > > to enforce something which is really a wart in my view, and indeed,
> > > as Gábor also notes, will create R source documentation that depends
> > > on implementation details of other package's documentation.
> > > I don't like it either, not at all.
> > >
> > > Martin
> > >
> > > > On 14/06/2020 6:26 a.m., Gábor Csárdi wrote:
> > > >> On Sun, Jun 14, 2020 at 10:44 AM Duncan Murdoch
> > > >> wrote:
> > > >> [...]
> > > >>>
> > > >>> I think the argument was that static builds of the help
> > > pages
> > would have
> > > >>> trouble resolving the links. With the current system, you
> > > can
> > build a
> > > >>> help page that links to a page in package foo even if
> > > package
> > foo is not
> > > >>> installed yet, and have the link work later after you
> > > install
> > foo.
> > > >>
> > > >> That is true, but it is also not a big problem, I think. The
> CRAN
> > > >> Windows R installer does indeed build static help pages by
> > default.
> > > >> But the built-in web server that serves these works around
> broken
> > > >> links by treating them as help topics instead of files. As
> > > you
> > know.
> > > >> :) So this would only be a problem if you wanted to serve
> > > the
> > static
> > > >> help pages with another web server. (Which is not a bad use
> > case, but
> > > >> then maybe Rd2HTML() can just resolve them as topics and
> > > avoid
> > the
> > > >> broken links.)
> > > >>
> > > >> Btw. the problem of linking to the wrong page is even worse
> wit
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
The Rd file is mplus.Rd, so
‘[lubridate:mplus]{lubridate::add_with_rollback()}’ would do.
Georgi Boshnakov
-Original Message-
From: R-package-devel On Behalf Of
David Hugh-Jones
Sent: 16 June 2020 07:51
To: Duncan Murdoch
Cc: List r-package-devel
Subject: Re: [R-pkg-devel] check cross-references error: Non-file
package-anchored link(s)
On this note, I just got
Non-file package-anchored link(s) in documentation object
'brk_width-for-datetime.Rd':
‘[lubridate:%m+%]{lubridate::add_with_rollback()}’
The correct filename appears to be %m+% in the lubridate help. Can anyone tell
me the right way to format this? I would work it out myself, but the check
didn't cause problems on the r-devel systems I tested with, so I'd be testing
blind.
Cheers,
David
On Mon, 15 Jun 2020 at 17:30, Duncan Murdoch
wrote:
> On 15/06/2020 12:05 p.m., Martin Maechler wrote:
> >>>>>> Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
> >
> > > I agree with almost everything you wrote, except one thing:
> > this
> isn't
> > > newly enforced, it has been enforced since the help system
> began. What
> > > I think is new is that there are now tests for it.
> > Previously
> those
> > > links just wouldn't work.
> >
> > > Duncan Murdoch
> >
> > Yes, to all... including Duncan's agreement with Gábor.
> >
> > Also, Duncan M earlier did mention that he had wanted to
> > *change* the link-to-file behavior for these cases (when he wrote
> > most of the Rd2html source code) but somehow did not get it.
>
> Actually, I don't think I pushed for this change at the time (or at
> least I didn't push much). I just wish now that I had, because I
> think it will be harder to do it now than it would have been then.
>
> Duncan
>
> >
> > And that's why we had partial workarounds (as the dynamic server
> > still finding the links under some circumstances).
> >
> > My personal opinions was also that "we" (the R community; i.e.,
> > people providing good patches to the R sources / collaborating with
> > R core / ...) should rather work to fix the current
> > design/implementation "infelicity" than the current checks starting
> > to enforce something which is really a wart in my view, and indeed,
> > as Gábor also notes, will create R source documentation that depends
> > on implementation details of other package's documentation.
> > I don't like it either, not at all.
> >
> > Martin
> >
> > > On 14/06/2020 6:26 a.m., Gábor Csárdi wrote:
> > >> On Sun, Jun 14, 2020 at 10:44 AM Duncan Murdoch
> > >> wrote:
> > >> [...]
> > >>>
> > >>> I think the argument was that static builds of the help
> > pages
> would have
> > >>> trouble resolving the links. With the current system, you
> > can
> build a
> > >>> help page that links to a page in package foo even if
> > package
> foo is not
> > >>> installed yet, and have the link work later after you
> > install
> foo.
> > >>
> > >> That is true, but it is also not a big problem, I think. The CRAN
> > >> Windows R installer does indeed build static help pages by
> default.
> > >> But the built-in web server that serves these works around broken
> > >> links by treating them as help topics instead of files. As
> > you
> know.
> > >> :) So this would only be a problem if you wanted to serve
> > the
> static
> > >> help pages with another web server. (Which is not a bad use
> case, but
> > >> then maybe Rd2HTML() can just resolve them as topics and
> > avoid
> the
> > >> broken links.)
> > >>
> > >> Btw. the problem of linking to the wrong page is even worse with
> > >> static builds of help pages, because if a link w/o a package
> (e.g.
> > >> \link{filter}) picks up the wrong package at install time,
> > then
> the
> > >> wrong link is hard-coded in the html. If you are building binary
> > >> packages, then they will link to the wrong help pages.
> > >>
> > >> WRE says that specifying the package in the link is rarely
> needed.
> > >> This was probably the case some time ago, especially when
> packages did
> > >> not have (compulsory) name
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On this note, I just got
Non-file package-anchored link(s) in documentation object
'brk_width-for-datetime.Rd':
‘[lubridate:%m+%]{lubridate::add_with_rollback()}’
The correct filename appears to be %m+% in the lubridate help. Can anyone
tell me the right way to format this? I would work it out myself, but the
check didn't cause problems on the r-devel systems I tested with, so I'd be
testing blind.
Cheers,
David
On Mon, 15 Jun 2020 at 17:30, Duncan Murdoch
wrote:
> On 15/06/2020 12:05 p.m., Martin Maechler wrote:
> >> Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
> >
> > > I agree with almost everything you wrote, except one thing: this
> isn't
> > > newly enforced, it has been enforced since the help system
> began. What
> > > I think is new is that there are now tests for it. Previously
> those
> > > links just wouldn't work.
> >
> > > Duncan Murdoch
> >
> > Yes, to all... including Duncan's agreement with Gábor.
> >
> > Also, Duncan M earlier did mention that he had wanted to
> > *change* the link-to-file behavior for these cases (when he
> > wrote most of the Rd2html source code) but somehow did not get it.
>
> Actually, I don't think I pushed for this change at the time (or at
> least I didn't push much). I just wish now that I had, because I think
> it will be harder to do it now than it would have been then.
>
> Duncan
>
> >
> > And that's why we had partial workarounds (as the dynamic server
> > still finding the links under some circumstances).
> >
> > My personal opinions was also that "we" (the R community; i.e.,
> > people providing good patches to the R sources / collaborating
> > with R core / ...) should rather work to fix the current
> > design/implementation "infelicity" than the current checks
> > starting to enforce something which is really a wart in my view,
> > and indeed, as Gábor also notes, will create R source
> > documentation that depends on implementation details of other
> > package's documentation.
> > I don't like it either, not at all.
> >
> > Martin
> >
> > > On 14/06/2020 6:26 a.m., Gábor Csárdi wrote:
> > >> On Sun, Jun 14, 2020 at 10:44 AM Duncan Murdoch
> > >> wrote:
> > >> [...]
> > >>>
> > >>> I think the argument was that static builds of the help pages
> would have
> > >>> trouble resolving the links. With the current system, you can
> build a
> > >>> help page that links to a page in package foo even if package
> foo is not
> > >>> installed yet, and have the link work later after you install
> foo.
> > >>
> > >> That is true, but it is also not a big problem, I think. The CRAN
> > >> Windows R installer does indeed build static help pages by
> default.
> > >> But the built-in web server that serves these works around broken
> > >> links by treating them as help topics instead of files. As you
> know.
> > >> :) So this would only be a problem if you wanted to serve the
> static
> > >> help pages with another web server. (Which is not a bad use
> case, but
> > >> then maybe Rd2HTML() can just resolve them as topics and avoid
> the
> > >> broken links.)
> > >>
> > >> Btw. the problem of linking to the wrong page is even worse with
> > >> static builds of help pages, because if a link w/o a package
> (e.g.
> > >> \link{filter}) picks up the wrong package at install time, then
> the
> > >> wrong link is hard-coded in the html. If you are building binary
> > >> packages, then they will link to the wrong help pages.
> > >>
> > >> WRE says that specifying the package in the link is rarely
> needed.
> > >> This was probably the case some time ago, especially when
> packages did
> > >> not have (compulsory) namespaces. But I am not sure if it still
> holds.
> > >> I would argue that it is better to specify the package you are
> linking
> > >> to. But the newly enforced requirement that we need to link to
> files
> > >> instead of topics makes this more error prone.
> > >>
> > >> Gabor
> > >>
> > >> [...]
> >
>
> __
> R-package-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>
[[alternative HTML version deleted]]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On 15/06/2020 12:05 p.m., Martin Maechler wrote:
Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
> I agree with almost everything you wrote, except one thing: this isn't
> newly enforced, it has been enforced since the help system began. What
> I think is new is that there are now tests for it. Previously those
> links just wouldn't work.
> Duncan Murdoch
Yes, to all... including Duncan's agreement with Gábor.
Also, Duncan M earlier did mention that he had wanted to
*change* the link-to-file behavior for these cases (when he
wrote most of the Rd2html source code) but somehow did not get it.
Actually, I don't think I pushed for this change at the time (or at
least I didn't push much). I just wish now that I had, because I think
it will be harder to do it now than it would have been then.
Duncan
And that's why we had partial workarounds (as the dynamic server
still finding the links under some circumstances).
My personal opinions was also that "we" (the R community; i.e.,
people providing good patches to the R sources / collaborating
with R core / ...) should rather work to fix the current
design/implementation "infelicity" than the current checks
starting to enforce something which is really a wart in my view,
and indeed, as Gábor also notes, will create R source
documentation that depends on implementation details of other
package's documentation.
I don't like it either, not at all.
Martin
> On 14/06/2020 6:26 a.m., Gábor Csárdi wrote:
>> On Sun, Jun 14, 2020 at 10:44 AM Duncan Murdoch
>> wrote:
>> [...]
>>>
>>> I think the argument was that static builds of the help pages would
have
>>> trouble resolving the links. With the current system, you can build a
>>> help page that links to a page in package foo even if package foo is
not
>>> installed yet, and have the link work later after you install foo.
>>
>> That is true, but it is also not a big problem, I think. The CRAN
>> Windows R installer does indeed build static help pages by default.
>> But the built-in web server that serves these works around broken
>> links by treating them as help topics instead of files. As you know.
>> :) So this would only be a problem if you wanted to serve the static
>> help pages with another web server. (Which is not a bad use case, but
>> then maybe Rd2HTML() can just resolve them as topics and avoid the
>> broken links.)
>>
>> Btw. the problem of linking to the wrong page is even worse with
>> static builds of help pages, because if a link w/o a package (e.g.
>> \link{filter}) picks up the wrong package at install time, then the
>> wrong link is hard-coded in the html. If you are building binary
>> packages, then they will link to the wrong help pages.
>>
>> WRE says that specifying the package in the link is rarely needed.
>> This was probably the case some time ago, especially when packages did
>> not have (compulsory) namespaces. But I am not sure if it still holds.
>> I would argue that it is better to specify the package you are linking
>> to. But the newly enforced requirement that we need to link to files
>> instead of topics makes this more error prone.
>>
>> Gabor
>>
>> [...]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
> Duncan Murdoch on Sun, 14 Jun 2020 07:28:03 -0400 writes:
> I agree with almost everything you wrote, except one thing: this isn't
> newly enforced, it has been enforced since the help system began. What
> I think is new is that there are now tests for it. Previously those
> links just wouldn't work.
> Duncan Murdoch
Yes, to all... including Duncan's agreement with Gábor.
Also, Duncan M earlier did mention that he had wanted to
*change* the link-to-file behavior for these cases (when he
wrote most of the Rd2html source code) but somehow did not get it.
And that's why we had partial workarounds (as the dynamic server
still finding the links under some circumstances).
My personal opinions was also that "we" (the R community; i.e.,
people providing good patches to the R sources / collaborating
with R core / ...) should rather work to fix the current
design/implementation "infelicity" than the current checks
starting to enforce something which is really a wart in my view,
and indeed, as Gábor also notes, will create R source
documentation that depends on implementation details of other
package's documentation.
I don't like it either, not at all.
Martin
> On 14/06/2020 6:26 a.m., Gábor Csárdi wrote:
>> On Sun, Jun 14, 2020 at 10:44 AM Duncan Murdoch
>> wrote:
>> [...]
>>>
>>> I think the argument was that static builds of the help pages would have
>>> trouble resolving the links. With the current system, you can build a
>>> help page that links to a page in package foo even if package foo is not
>>> installed yet, and have the link work later after you install foo.
>>
>> That is true, but it is also not a big problem, I think. The CRAN
>> Windows R installer does indeed build static help pages by default.
>> But the built-in web server that serves these works around broken
>> links by treating them as help topics instead of files. As you know.
>> :) So this would only be a problem if you wanted to serve the static
>> help pages with another web server. (Which is not a bad use case, but
>> then maybe Rd2HTML() can just resolve them as topics and avoid the
>> broken links.)
>>
>> Btw. the problem of linking to the wrong page is even worse with
>> static builds of help pages, because if a link w/o a package (e.g.
>> \link{filter}) picks up the wrong package at install time, then the
>> wrong link is hard-coded in the html. If you are building binary
>> packages, then they will link to the wrong help pages.
>>
>> WRE says that specifying the package in the link is rarely needed.
>> This was probably the case some time ago, especially when packages did
>> not have (compulsory) namespaces. But I am not sure if it still holds.
>> I would argue that it is better to specify the package you are linking
>> to. But the newly enforced requirement that we need to link to files
>> instead of topics makes this more error prone.
>>
>> Gabor
>>
>> [...]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
I agree with almost everything you wrote, except one thing: this isn't
newly enforced, it has been enforced since the help system began. What
I think is new is that there are now tests for it. Previously those
links just wouldn't work.
Duncan Murdoch
On 14/06/2020 6:26 a.m., Gábor Csárdi wrote:
On Sun, Jun 14, 2020 at 10:44 AM Duncan Murdoch
wrote:
[...]
I think the argument was that static builds of the help pages would have
trouble resolving the links. With the current system, you can build a
help page that links to a page in package foo even if package foo is not
installed yet, and have the link work later after you install foo.
That is true, but it is also not a big problem, I think. The CRAN
Windows R installer does indeed build static help pages by default.
But the built-in web server that serves these works around broken
links by treating them as help topics instead of files. As you know.
:) So this would only be a problem if you wanted to serve the static
help pages with another web server. (Which is not a bad use case, but
then maybe Rd2HTML() can just resolve them as topics and avoid the
broken links.)
Btw. the problem of linking to the wrong page is even worse with
static builds of help pages, because if a link w/o a package (e.g.
\link{filter}) picks up the wrong package at install time, then the
wrong link is hard-coded in the html. If you are building binary
packages, then they will link to the wrong help pages.
WRE says that specifying the package in the link is rarely needed.
This was probably the case some time ago, especially when packages did
not have (compulsory) namespaces. But I am not sure if it still holds.
I would argue that it is better to specify the package you are linking
to. But the newly enforced requirement that we need to link to files
instead of topics makes this more error prone.
Gabor
[...]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On Sun, Jun 14, 2020 at 10:44 AM Duncan Murdoch
wrote:
[...]
>
> I think the argument was that static builds of the help pages would have
> trouble resolving the links. With the current system, you can build a
> help page that links to a page in package foo even if package foo is not
> installed yet, and have the link work later after you install foo.
That is true, but it is also not a big problem, I think. The CRAN
Windows R installer does indeed build static help pages by default.
But the built-in web server that serves these works around broken
links by treating them as help topics instead of files. As you know.
:) So this would only be a problem if you wanted to serve the static
help pages with another web server. (Which is not a bad use case, but
then maybe Rd2HTML() can just resolve them as topics and avoid the
broken links.)
Btw. the problem of linking to the wrong page is even worse with
static builds of help pages, because if a link w/o a package (e.g.
\link{filter}) picks up the wrong package at install time, then the
wrong link is hard-coded in the html. If you are building binary
packages, then they will link to the wrong help pages.
WRE says that specifying the package in the link is rarely needed.
This was probably the case some time ago, especially when packages did
not have (compulsory) namespaces. But I am not sure if it still holds.
I would argue that it is better to specify the package you are linking
to. But the newly enforced requirement that we need to link to files
instead of topics makes this more error prone.
Gabor
[...]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On 13/06/2020 9:00 p.m., Gábor Csárdi wrote:
On Sat, Jun 13, 2020 at 8:10 PM Duncan Murdoch wrote:
On 13/06/2020 1:17 p.m., Zhian Kamvar wrote:
[...]
Is this a new policy?
Zhian, it seems that some of the problematic links are created by
roxygen2. You can fix these using this PR:
https://github.com/r-lib/roxygen2/pull/1109
You can install this branch with
remotes::install_github("r-lib/roxygen2@fix/link-to-file")
To fix the remaining ones, you need to modify your \link[]{} macros or
switch them to roxygen [pkg::fun()] links.
[...]
This is probably a new test of the long-time requirement that links
should be to filenames, not aliases, when they go to other packages.
I really like how the help system resolves links based on _topics_,
even for cross-package links. So I admit that I did not follow this
requirement too closely. It is better to link to topics instead of
files, because then links are independent of how the manual is
organized into files. E.g. it is not uncommon to split up a help file
that used to document multiple functions, into several files, because
the functions gain more functionality, or need more examples, etc. and
the manual page is getting less focused and harder to follow. It is
perfectly natural that the manual of a package is evolving together
with the code.
With enforcing this requirement, such documentation changes are
considered as breaking changes. If we need to link to files, then what
we get is more broken links, and more forced package updates, just to
fix the broken links. In particular, if a package moves a help topic
to another help file in a new release, then other packages linking to
this topic have to update their links, and if these happened to be
installed together with the old version of the linked package, they'll
have a broken link. This is a pity, because finding the right help
files is easy to automate, and in fact the help system already
supports it perfectly well.
As far as I can tell the only alternative of linking to the file is
using an unqualified link, i.e. not specifying the target package at
all. The help system can do the lookup at render time, and this is
usually OK, but for a non-trivial number of cases it is not, because
the resolution of the link depends on what packages are currently
loaded. If the right package is not loaded, then the link will
potentially go to the wrong help file, which is absurd. Or, if
multiple packages have the required topic, the user is presented with
a menu, which is also confusing. OTOH the manual authors know
perfectly well which package they want to link to, they just can't
specify it any more...
I am probably missing something, but what do we gain from linking to
files, instead of topics? Especially that linking to topics already
works perfectly well?
I think the argument was that static builds of the help pages would have
trouble resolving the links. With the current system, you can build a
help page that links to a page in package foo even if package foo is not
installed yet, and have the link work later after you install foo.
Duncan Murdoch
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On Sat, Jun 13, 2020 at 8:10 PM Duncan Murdoch wrote:
>
> On 13/06/2020 1:17 p.m., Zhian Kamvar wrote:
[...]
> > Is this a new policy?
Zhian, it seems that some of the problematic links are created by
roxygen2. You can fix these using this PR:
https://github.com/r-lib/roxygen2/pull/1109
You can install this branch with
remotes::install_github("r-lib/roxygen2@fix/link-to-file")
To fix the remaining ones, you need to modify your \link[]{} macros or
switch them to roxygen [pkg::fun()] links.
[...]
> This is probably a new test of the long-time requirement that links
> should be to filenames, not aliases, when they go to other packages.
I really like how the help system resolves links based on _topics_,
even for cross-package links. So I admit that I did not follow this
requirement too closely. It is better to link to topics instead of
files, because then links are independent of how the manual is
organized into files. E.g. it is not uncommon to split up a help file
that used to document multiple functions, into several files, because
the functions gain more functionality, or need more examples, etc. and
the manual page is getting less focused and harder to follow. It is
perfectly natural that the manual of a package is evolving together
with the code.
With enforcing this requirement, such documentation changes are
considered as breaking changes. If we need to link to files, then what
we get is more broken links, and more forced package updates, just to
fix the broken links. In particular, if a package moves a help topic
to another help file in a new release, then other packages linking to
this topic have to update their links, and if these happened to be
installed together with the old version of the linked package, they'll
have a broken link. This is a pity, because finding the right help
files is easy to automate, and in fact the help system already
supports it perfectly well.
As far as I can tell the only alternative of linking to the file is
using an unqualified link, i.e. not specifying the target package at
all. The help system can do the lookup at render time, and this is
usually OK, but for a non-trivial number of cases it is not, because
the resolution of the link depends on what packages are currently
loaded. If the right package is not loaded, then the link will
potentially go to the wrong help file, which is absurd. Or, if
multiple packages have the required topic, the user is presented with
a menu, which is also confusing. OTOH the manual authors know
perfectly well which package they want to link to, they just can't
specify it any more...
I am probably missing something, but what do we gain from linking to
files, instead of topics? Especially that linking to topics already
works perfectly well?
Gabor
[...]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
On 13/06/2020 1:17 p.m., Zhian Kamvar wrote:
Hello,
I noticed a strange error pop up for R-devel (2020-06-12 r78687) check on
travis:
https://travis-ci.org/github/grunwaldlab/poppr/jobs/697831376#L4653-L4654
* checking Rd cross-references ... WARNING
Non-file package-anchored link(s) in documentation object 'aboot.Rd':
‘[ape:phylo]{ape::phylo()}’
I looked at the Cross-reference section of WRE, but I couldn't find any mention
of non-file package-anchored links being a problem:
https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Cross_002dreferences
Is this a new policy?
This is probably a new test of the long-time requirement that links
should be to filenames, not aliases, when they go to other packages.
WRE says
"There are two other forms of optional argument specified as
\link[pkg]{foo} and \link[pkg:bar]{foo} to link to the package pkg, to
files foo.html and bar.html respectively."
The problem is that `phylo` is documented in the read.tree.Rd file in
ape, so your link needs to be
\link[ape:read.tree]{ape::phylo()}
I wish I had fixed this inconsistency years ago when I rewrote the Rd
code, but I didn't. It would have been painful at the time (there were
already thousands of CRAN packages, and lots would have needed fixing),
but would be much worse now.
Another design flaw that I didn't fix is that you can have an Rd with
\name{foo} and no \alias{foo}, and searching ?foo won't find it. In
that case I failed to convince other R core members that it would have
been a good change.
Duncan Murdoch
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
[R-pkg-devel] check cross-references error: Non-file package-anchored link(s)
Hello,
I noticed a strange error pop up for R-devel (2020-06-12 r78687) check on
travis:
https://travis-ci.org/github/grunwaldlab/poppr/jobs/697831376#L4653-L4654
* checking Rd cross-references ... WARNING
Non-file package-anchored link(s) in documentation object 'aboot.Rd':
‘[ape:phylo]{ape::phylo()}’
I looked at the Cross-reference section of WRE, but I couldn't find any mention
of non-file package-anchored links being a problem:
https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Cross_002dreferences
Is this a new policy?
All the best,
Zhian
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
