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_fds html
> 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 <j.gore...@wit.edu.pl> 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, <rwoldf...@uwaterloo.ca> wrote:
>>>
>>> Thank you!
>>>
>>> -----Original Message-----
>>> From: Gábor Csárdi <csardi.ga...@gmail.com>
>>> Date: Tuesday, June 16, 2020 at 4:32 PM
>>> To: Wayne Oldford <rwoldf...@uwaterloo.ca>
>>> Cc: List r-package-devel <r-package-devel@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 <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
>>> > \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-boun...@r-project.org> on
>>> behalf of Georgi Boshnakov <georgi.boshna...@manchester.ac.uk>
>>> > Date: Tuesday, June 16, 2020 at 9:27 AM
>>> > To: Gábor Csárdi <csardi.ga...@gmail.com>, Duncan Murdoch
>>> <murdoch.dun...@gmail.com>
>>> > Cc: List r-package-devel <r-package-devel@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-boun...@r-project.org> On
>>> Behalf Of Gábor Csárdi
>>> > Sent: 16 June 2020 13:44
>>> > To: Duncan Murdoch <murdoch.dun...@gmail.com>
>>> > Cc: List r-package-devel <r-package-devel@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.dun...@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@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
>>> >
>>> >
>>> > ______________________________________________
>>> > 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
>
> ______________________________________________
> 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
