>>>>> "HenrikB" == Henrik Bengtsson <h...@stat.berkeley.edu>
>>>>> on Wed, 11 Nov 2009 15:29:06 +0100 writes:
HenrikB> 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.
HenrikB> I'd say the union across all OSes should be mentioned under the
HenrikB> \arguments{}. Then one can add to \item{} making it clear that
this
HenrikB> is specific to a particular OS, e.g. \item{recursive}{(Unix only)
HenrikB> ...}. That is in line with how some arguments are flagged
HenrikB> "(optional)" in \item{}.
I entirely agree with this
(1) show union of arguments across OSes
(2) {typically, there will be exceptions}, just mention within each
argument's \item{} how it applies on different platforms.
Martin
HenrikB> At a minimum it is useful to have a note that makes the
HenrikB> reader/users/developer aware that the function differ between
HenrikB> platforms. (With the new help system, this can be automated if
such
HenrikB> functions have been flagged with an attribute, e.g. attr(fcn,
HenrikB> "differAcrossOSes") <- TRUE)
HenrikB> Just thoughts.
HenrikB> /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
>>>
>>
>>
HenrikB> ______________________________________________
HenrikB> R-devel@r-project.org mailing list
HenrikB> https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
