[R-pkg-devel] Rd files: using \link[pkg]{foo} when file names differ between OSs

[Duncan Murdoch]

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.

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.

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
>