From murdoch at stats.uwo.ca  Wed Nov 11 11:36:33 2009
From: murdoch at stats.uwo.ca (Duncan Murdoch)
Date: Wed, 11 Nov 2009 05:36:33 -0500
Subject: [Rd] typo in docs for unlink()
In-Reply-To: <4AFA3AA7.8080104@acm.org>
References: <4AFA350D.7060303@acm.org> <4AFA3AA7.8080104@acm.org>
Message-ID: <4AFA93B1.6050508@stats.uwo.ca>

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.

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 at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel



[Rd] typo in docs for unlink()
Duncan Murdoch