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

2018-04-18 Thread Ramon Diaz-Uriarte 

Dear Duncan,

On Mon, 16-April-2018, at 17:52:10, Duncan Murdoch  
wrote:
> 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

Thanks. I wasn't aware that was possible.



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

I think the previous one is better (actually, for my specific cases right
now, I was able to solve the problem using \link{foo} since only one
packages offers help on the topic I link to).



Best,

R.


>
> Duncan Murdoch
>> 
>> 
>> 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
>> 
>> Phone: +34-91-497-2412
>> 
>> Email: rdia...@gmail.com
>> ramon.d...@iib.uam.es
>> 
>> http://ligarto.org/rdiaz
>> 
>> __
>> R-package-devel@r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>> 


-- 
Ramon Diaz-Uriarte
Department of Biochemistry, Lab B-25
Facultad de Medicina
Universidad Autónoma de Madrid 
Arzobispo Morcillo, 4
28029 Madrid
Spain

Phone: +34-91-497-2412

Email: rdia...@gmail.com
   ramon.d...@iib.uam.es

http://ligarto.org/rdiaz

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

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

2018-04-16 Thread Duncan Murdoch 

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

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

2018-04-16 Thread Martin Morgan 



On 04/16/2018 12:31 PM, Duncan Murdoch wrote:

On 16/04/2018 12:06 PM, Martin Maechler wrote:

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


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


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


  - 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

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

2018-04-16 Thread Duncan Murdoch 

On 16/04/2018 12:06 PM, Martin Maechler wrote:

Duncan Murdoch 
 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



__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel

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

2018-04-16 Thread Martin Maechler 
> Duncan Murdoch 
> 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

__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel