ifdef for linking to windows/unix-only man pages

[zeileis]

Sometimes you need to link to system-specific documentation (windows only or unix only) and the standard way of doing this in Rd is to use #ifdef constructs, see: https://CRAN.R-project.org/doc/manuals/r-release/R-exts.html#Platform_002dspecific-sections. However, this currently does not seem to work in pkgdown, leading to Unknown tag: #ifdef/tag messages and omission of the corresponding conditional documentation.

Is there some workardound for this or should this be declared differently for pkgdown?

Concrete example from one of our packages: For parallelization we use parallel::mclapply() except on Windows where it isn't available and we resort to parallel::parLapply(). Hence, the Rd text has:

... use either \code{\link[parallel:clusterApply]{parLapply}} (on Windows) or 
#ifdef windows
\code{\link[parallel:mcdummies]{mclapply}}
#endif
#ifdef unix
\code{\link[parallel]{mclapply}}
#endif 
(otherwise) ...

Depending on the system on which this package is installed, this will link to the "mcdummies" help page (on Windows) or the "mclapply" help page (otherwise). I'm not sure what would be the best general solution for pkgdown, e.g., always use the first element only or present both elements side by side with some markup?

Note also that on rdrr.io the corresponding help pages are in unix/ and windows/ subdirectories:
https://rdrr.io/r/parallel/unix/mclapply.html
https://rdrr.io/r/parallel/windows/mcdummies.html

[hadley]

I think displaying different documentation on different operation systems is a recipe for confusion (you're better off having (e.g) sections for "windows" and "linux") but since some packages do only provide docs on some platforms, you still need conditional linking, so I've added support for #ifdef and #ifndef. I've hard coded the "current" OS to linux, so that you get the same results when (e.g.) testing locally on windows and deploying on linux.

[zeileis]

Thanks for the quick fix! I agree that OS-specific sections would be better than entire OS-specific Rd pages. I think fixing the OS to unix is a pragmatic solution. (Except maybe for Windows-only packages.)
But the links to rdrr.io are currently not resolved correctly because rdrr.io uses the unix/ and windows/ subdirectories. Therefore, in my example above, the new pkgdown devel version (I used 1.5.1.9000) links to
https://rdrr.io/r/parallel/mclapply.html rather than
https://rdrr.io/r/parallel/unix/mclapply.html.

[hadley]

Oh that’s a different part of the code - do you mind filing a separate issue?