Re: [Rd] typo in docs for unlink()

From: Duncan Murdoch <murdoch_at_stats.uwo.ca>
Date: Wed, 11 Nov 2009 06:55:37 -0500

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
>

______________________________________________
R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Wed 11 Nov 2009 - 11:58:21 GMT

This archive was generated by hypermail 2.2.0 : Wed 11 Nov 2009 - 15:40:23 GMT