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

[Martin Maechler]

>>>>> 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.

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