[R-pkg-devel] Rd files: using \link[pkg]{foo} when file names differ between OSs
Duncan Murdoch
murdoch.duncan at gmail.com
Mon Apr 16 19:57:35 CEST 2018
On 16/04/2018 1:06 PM, Martin Morgan wrote:
>
>
> On 04/16/2018 12:31 PM, Duncan Murdoch wrote:
>> On 16/04/2018 12:06 PM, Martin Maechler wrote:
>>>>>>>> Duncan Murdoch <murdoch.duncan at gmail.com>
>>>>>>>> on Mon, 16 Apr 2018 11:52:10 -0400 writes:
>>>
>>> > On 16/04/2018 11:35 AM, Ramon Diaz-Uriarte wrote:
>>> >> Dear All,
>>> >>
>>> >> Two recent threads in the bioconductor devel mailing list
>>> >> (https://stat.ethz.ch/pipermail/bioc-devel/2018-April/013156.html
>>> >> and
>>> >> https://stat.ethz.ch/pipermail/bioc-devel/2018-April/013259.html)
>>> >> are related to packages that have different names of html
>>> >> files in different operating systems.
>>> >>
>>> >> For example, parallel has a file called mclapply in
>>> >> Linux. So using, from the Rd file of another package,
>>> >> \link[parallel]{mclapply} works fine under Linux, but
>>> >> does not under Windows, because there is no mclapply.html
>>> >> file in Windows (there is a mcdummies file).
>>> >>
>>> >>
>>> >> Is there any recommended way to proceed in these cases?
>>> >>
>>> >>
>>> >> Yes, section 2.5 of Writing R Extensions indicates that
>>> >> \link[pkg]{foo} and \link[pkg:bar]{foo} are rarely
>>> >> needed; so the simplest way to proceed would be to avoid
>>> >> \link[pkg]{foo} and \link[pkg:bar]{foo}. I am asking for
>>> >> the cases where, as noted in 2.5, "more than one package
>>> >> offers help on a topic".
>>>
>>> > You could make the links conditional on the OS. For example,
>>>
>>> > #ifdef windows
>>> > See \link[parallel]{mcdummies}.
>>> > #endif
>>> > #ifdef unix
>>> > See \link[parallel]{mclapply}.
>>> > #endif
>>>
>>> > The other possibility (useful if there are major differences
>>> between the
>>> > platforms) is to have two copies of the help file, one in
>>> man/unix, one
>>> > in man/windows, but that doesn't seem appropriate from your
>>> description.
>>>
>>> > Duncan Murdoch
>>>
>>> and mid-term, I really think R and (CRAN, Bioc, ...) packages
>>> should not do what we (R core) did here.
>>> Rather, \alias{mclapply} should exist both for windows and
>>> non-windows, and hence \link{mclapply} would just work.
>
> \alias{mclapply} does exist...
>
>>
>> I forget whether that would work here: parallel being a base package
>> (used by the package in question?) might mean it would be found without
>> the [parallel] in the link. But in general, links to other packages
>> using [pkg] go to the *filename*, not to the alias. This oddity happens
>> because we want the links to work even if the referenced package is
>> installed later than the Rd file is processed.
>
> People are quite concerned about fixing the 'WARNING' this generates.
> However from the text
>
> file link 'mclapply' in package 'parallel' does not exist and so has
> been treated as a topic
>
> the help pages are actually constructed correctly, finding the page on
> which the topic (aka alias) 'mclapply' is defined. This contrasts with a
> completely incorrect link (e.g., \link[stats]{mclapply}) generating a
> warning
>
> missing file link
>
> and unable to link to the mclapply topic.
>
> Perhaps the WARNING from \link[parallel]{mclapply} should be a NOTE?
>
> There are other oddities in the threads that Ramon indicates
>
> - WARNINGs from \link[foo]{bar} that should really be
> \link[foo:baz]{bar} often only appear on Windows (parallel's use of
> mcdummies is a special case here). Shouldn't they be
> platform-independent? An example is
>
>
> http://bioconductor.org/checkResults/3.7/bioc-LATEST/ADaCGH2/tokay2-checksrc.html
>
> where as.MAList is defined in a file called asmalist.Rd so
> \link[limma]{as.MAList} is incorrect. It generates a warning only on our
> Windows machine (tokay2) not Linux or Mac. I had some recollection of
> Windows-specific help system behavior, but I think this dates back to
> the .chm days...
Yes, that looks like an issue in the Linux checks.
>
> - There were a spate of independent posts about this, suggesting that
> this is relatively new phenomenon (though it could also be that
> maintainers have been busy preparing their packages for the next
> release, so are now noticing the problem...)
The fact that cross-package links go to files rather than aliases is
very old, but the checks may be newer.
>
> - It doesn't seem like good practice to link to the file name, which
> seems an internal aspect of a package, rather than to the alias, which
> seems at least for symbols to be a user-facing public aspect of the package.
I agree, but as I said, this is very old. It was old when I wrote the
Rd parser. I vaguely recall that the possibility of a change was
considered and rejected, but I'm not sure about that.
Changing it to use only topics would likely cause problems for people
who are not getting warnings now. Perhaps it would be sensible to
switch from filename to topic without a warning if the referenced
package is available for checking, only issuing the warning if the check
machine can't verify that the link is good.
Duncan Murdoch
>
> - And finally I did make an svn commit related to this, so am
> sensitive to blundering here
>
> R-devel/src/library/tools/R$ svn log -c74129
> ------------------------------------------------------------------------
> r74129 | morgan | 2018-01-17 16:52:53 -0500 (Wed, 17 Jan 2018) | 10 lines
>
> correct warning when \link[base]{foo} is incorrect
>
> - now "missing file link" rather than "file link 'foo' in package 'base'
> does not exist and will be treated as a topic" (foo is _not_ a topic
> in base; the link to foo.html is missing)
> - vice-versa for \link[base]{rbind} (rbind _is_ a topic in base,
> documented in
> cbind.html, and will be resolved by the help system)
> - see https://stat.ethz.ch/pipermail/r-devel/2009-October/055287.html and
> c50198
>
> ------------------------------------------------------------------------
>
> - There is a possibility that some of the oddities are Bioc
> build-system specific, and I really have not had a chance to dig to the
> bottom of this to my satisfaction.
>
> Martin
>
>
>>
>> The reason the file was named "mclapply" in man/unix but "mcdummies" in
>> man/windows was likely to save some time: there are several aliases
>> documented in that one file on Windows, but they are in separate files
>> on Unix.
>>
>> Duncan Murdoch
>>
>>>
>>> Martin Maechler
>>>
>>>
>>> >> Thanks,
>>> >> R.
>>>
>>> >> --
>>> >> Ramon Diaz-Uriarte
>>> >> Department of Biochemistry, Lab B-25
>>> >> Facultad de Medicina
>>> >> Universidad Autónoma de Madrid
>>> >> Arzobispo Morcillo, 4
>>> >> 28029 Madrid
>>> >> Spain
>>>
>>
>> ______________________________________________
>> R-package-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>
>
> This email message may contain legally privileged and/or confidential information. If you are not the intended recipient(s), or the employee or agent responsible for the delivery of this message to the intended recipient(s), you are hereby notified that any disclosure, copying, distribution, or use of this email message is prohibited. If you have received this message in error, please notify the sender immediately by e-mail and delete this email message from your computer. Thank you.
>
More information about the R-package-devel
mailing list