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-pkg-devel] check cross-references error: Non-file package-anchored link(s)
16 messages · Zhian Kamvar, Martin Maechler, Duncan Murdoch +4 more
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
On Sat, Jun 13, 2020 at 8:10 PM Duncan Murdoch <murdoch.duncan at gmail.com> 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 at 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 [...]
On 13/06/2020 9:00 p.m., G?bor Cs?rdi wrote:
On Sat, Jun 13, 2020 at 8:10 PM Duncan Murdoch <murdoch.duncan at gmail.com> 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 at 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
On Sun, Jun 14, 2020 at 10:44 AM Duncan Murdoch
<murdoch.duncan at gmail.com> 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
[...]
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 <murdoch.duncan at gmail.com> 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
[...]
1 day later
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
>> <murdoch.duncan at gmail.com> 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
>>
>> [...]
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
>> <murdoch.duncan at gmail.com> 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
>>
>> [...]
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 <murdoch.duncan at gmail.com>
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
>> <murdoch.duncan at gmail.com> 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 at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
The Rd file is mplus.Rd, so ?[lubridate:mplus]{lubridate::add_with_rollback()}? would do.
Georgi Boshnakov
-----Original Message-----
From: R-package-devel <r-package-devel-bounces at r-project.org> On Behalf Of David Hugh-Jones
Sent: 16 June 2020 07:51
To: Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: List r-package-devel <r-package-devel at r-project.org>
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 <murdoch.duncan at gmail.com>
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
>> <murdoch.duncan at gmail.com> 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 at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
______________________________________________ R-package-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Thank you so much! David On Tue, 16 Jun 2020 at 08:36, Georgi Boshnakov <
georgi.boshnakov at 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 <r-package-devel-bounces at r-project.org> On Behalf
Of David Hugh-Jones
Sent: 16 June 2020 07:51
To: Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: List r-package-devel <r-package-devel at r-project.org>
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 <murdoch.duncan at gmail.com>
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
>> <murdoch.duncan at gmail.com> 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 at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
[[alternative HTML version deleted]]
______________________________________________ R-package-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
On Mon, Jun 15, 2020 at 5:30 PM Duncan Murdoch <murdoch.duncan at gmail.com> 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
[...]
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 <r-package-devel-bounces at r-project.org> On Behalf Of G?bor Cs?rdi
Sent: 16 June 2020 13:44
To: Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: List r-package-devel <r-package-devel at r-project.org>
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 <murdoch.duncan at gmail.com> 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 at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
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 <r-package-devel-bounces at r-project.org> on behalf of Georgi Boshnakov <georgi.boshnakov at manchester.ac.uk>
Date: Tuesday, June 16, 2020 at 9:27 AM
To: G?bor Cs?rdi <csardi.gabor at gmail.com>, Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: List r-package-devel <r-package-devel at r-project.org>
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 <r-package-devel-bounces at r-project.org> On Behalf Of G?bor Cs?rdi
Sent: 16 June 2020 13:44
To: Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: List r-package-devel <r-package-devel at r-project.org>
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 <murdoch.duncan at gmail.com> 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 at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
______________________________________________
R-package-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
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 <rwoldford at 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
\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 <r-package-devel-bounces at r-project.org> on behalf of Georgi Boshnakov <georgi.boshnakov at manchester.ac.uk>
Date: Tuesday, June 16, 2020 at 9:27 AM
To: G?bor Cs?rdi <csardi.gabor at gmail.com>, Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: List r-package-devel <r-package-devel at r-project.org>
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 <r-package-devel-bounces at r-project.org> On Behalf Of G?bor Cs?rdi
Sent: 16 June 2020 13:44
To: Duncan Murdoch <murdoch.duncan at gmail.com>
Cc: List r-package-devel <r-package-devel at r-project.org>
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 <murdoch.duncan at gmail.com> 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 at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
______________________________________________
R-package-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
______________________________________________
R-package-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Thank you!
?-----Original Message-----
From: G?bor Cs?rdi <csardi.gabor at gmail.com>
Date: Tuesday, June 16, 2020 at 4:32 PM
To: Wayne Oldford <rwoldford at uwaterloo.ca>
Cc: List r-package-devel <r-package-devel at r-project.org>
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 <rwoldford at 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
> \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 <r-package-devel-bounces at r-project.org> on behalf of Georgi Boshnakov <georgi.boshnakov at manchester.ac.uk>
> Date: Tuesday, June 16, 2020 at 9:27 AM
> To: G?bor Cs?rdi <csardi.gabor at gmail.com>, Duncan Murdoch <murdoch.duncan at gmail.com>
> Cc: List r-package-devel <r-package-devel at r-project.org>
> 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 <r-package-devel-bounces at r-project.org> On Behalf Of G?bor Cs?rdi
> Sent: 16 June 2020 13:44
> To: Duncan Murdoch <murdoch.duncan at gmail.com>
> Cc: List r-package-devel <r-package-devel at r-project.org>
> 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 <murdoch.duncan at gmail.com> 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 at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
> ______________________________________________
> R-package-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>
>
> ______________________________________________
> R-package-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel