[Rd] typo in docs for unlink()

[Henrik Bengtsson]

On Wed, Nov 11, 2009 at 12:55 PM, Duncan Murdoch <murdoch at stats.uwo.ca> wrote:
> 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.

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