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

From: Martin Maechler <maechler_at_stat.math.ethz.ch>
Date: Thu, 12 Nov 2009 09:24:55 +0100

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

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

HenrikB> ______________________________________________

HenrikB> R-devel_at_r-project.org mailing list     HenrikB> 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 Thu 12 Nov 2009 - 08:28:46 GMT

This archive was generated by hypermail 2.2.0 : Thu 12 Nov 2009 - 10:30:24 GMT