[Rd] typo in docs for unlink()

[Duncan Murdoch]

Henrik Bengtsson wrote:
> On Wed, Nov 11, 2009 at 11:36 AM, Duncan Murdoch <murdoch at 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.

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