On Sat, Jun 13, 2020 at 8:10 PM Duncan Murdoch <murdoch.dun...@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@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
