On Wed, Nov 11, 2009 at 12:55 PM, Duncan Murdoch <murd...@stats.uwo.ca> wrote: > Henrik Bengtsson wrote: >> >> On Wed, Nov 11, 2009 at 11:36 AM, Duncan Murdoch <murd...@stats.uwo.ca> >> wrote: >> >>> >>> On 10/11/2009 11:16 PM, Tony Plate wrote: >>> >>>> >>>> PS, I should have said that I'm reading the docs for unlink in R-2.10.0 >>>> on >>>> a Linux system. The docs that appear in a Windows installation of R are >>>> different (the Windows docs do not mention that not all systems support >>>> recursive=TRUE). >>>> >>>> Here's a plea for docs to be uniform across all systems! Trying to >>>> write >>>> R code that works on all systems is much harder when the docs are >>>> different >>>> across systems, and you might only see system specific notes on a >>>> different >>>> system than the one you're working on. >>>> >>> >>> That's a good point, but in favour of the current practice, it is very >>> irritating when searches take you to functions that don't work on your >>> system. >>> >>> One thing that might be possible is to render all versions of the help on >>> all systems, but with some sort of indicator (e.g. a colour change) to >>> indicate things that don't apply on your system, or only apply on your >>> system. I think the hardest part of doing this would be designing the >>> output; actually implementing it would not be so bad. >>> >> >> I 2nd this wishlist - to see the documentation for all (known) >> platforms, if possible. > > One way to see this is to read the .Rd files, rather than the rendered > version. >> >> A very simple solution is to have an Rd >> section on operating-system specific features, e.g. >> \section{Differences between operating systems}{...}. >> >> This would decrease the trial and error of producing cross-platform code. >> >> > > This is not easy. For example, with unlink should the "recursive=TRUE" > option not be mentioned except in the platform-specific section? I think > that would make the docs a lot harder to read.
I'd say the union across all OSes should be mentioned under the \arguments{}. Then one can add to \item{} making it clear that this is specific to a particular OS, e.g. \item{recursive}{(Unix only) ...}. That is in line with how some arguments are flagged "(optional)" in \item{}. At a minimum it is useful to have a note that makes the reader/users/developer aware that the function differ between platforms. (With the new help system, this can be automated if such functions have been flagged with an attribute, e.g. attr(fcn, "differAcrossOSes") <- TRUE) Just thoughts. /Henrik > > Duncan Murdoch > >> /Henrik >> >> >>> >>> Duncan Murdoch >>> >>> >>>> >>>> -- Tony Plate >>>> >>>> Tony Plate wrote: >>>> >>>>> >>>>> The VALUE section in the help for 'unlink' says: >>>>> >>>>> | 0| for success, |1| for failure. Not deleting a non-existent file is >>>>> not a failure, nor is being unable to delete a directory if |recursive >>>>> = >>>>> FALSE|. However, missing values in |x| result are regarded as failures. >>>>> >>>>> The last phrase doesn't make sense to me. Should it be either "missing >>>>> values in x are regarded as failures" or "missing values in x result in >>>>> failure" ? >>>>> >>>>> Also, after reading the docs, I'm still unable to work out if unlink() >>>>> will return 1 when the user tries to recursively delete a directory on >>>>> systems that don't support recursive=T. >>>>> >>>>> The DETAILS section says "recursive=TRUE is not supported on all >>>>> platforms, and may be ignored, with a warning", which could be >>>>> interpreted >>>>> as implying no special action when recursive=TRUE is not implemented >>>>> (other >>>>> than a warning()), and the VALUE section doesn't say what the return >>>>> value >>>>> will be under such conditions. >>>>> >>>>> I've skimmed the various *_unlink functions in src/main/platform.c, and >>>>> it looks like they all implement recursive=TRUE, so I'm still in the >>>>> dark >>>>> about the required behavior on systems that don't support it. Could >>>>> this be >>>>> clarified in the help file? >>>>> >>>>> thanks, >>>>> >>>>> Tony Plate >>>>> >>>>> ______________________________________________ >>>>> R-devel@r-project.org mailing list >>>>> https://stat.ethz.ch/mailman/listinfo/r-devel >>>>> >>>>> >>>> >>>> ______________________________________________ >>>> R-devel@r-project.org mailing list >>>> https://stat.ethz.ch/mailman/listinfo/r-devel >>>> >>> >>> ______________________________________________ >>> R-devel@r-project.org mailing list >>> https://stat.ethz.ch/mailman/listinfo/r-devel >>> >>> >> >> ______________________________________________ >> R-devel@r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/r-devel >> > > ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel