R devel - Nov 2009 - typo in docs for unlink()

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

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.

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

>>>>> "KH" == Kurt Hornik <Kurt.Hornik at
wu.ac.at>
>>>>>     on Thu, 12 Nov 2009 12:15:49 +0100 writes:
((only to R-core, not R-devel -- I think R-devel is find and so
  back-post there ))
>>>>> Martin Maechler writes:
>>>>> "HenrikB" == Henrik Bengtsson <hb at
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 <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.

    KH> I'm not getting it.  How will you then do with the mismatches
between
    KH> the \usage and the \arguments?

Good point.  Of course, you are thinking about  'R CMD check'ing
the "base R" code,
where then, \usage{} is checked to match the actually existing
formal argument list of the function.

I see two possibilities (and there may be more) :

- Either we define Rd-markup for arguments that may be allowed
  to be missing (on some platforms)

- or we also extend the formal argument list of the function
  to be the same on all platforms.
  On those platforms where an argument is not sensible,
  users will get an error (or warning) when they specify (a
  non-default value for) it anyway.

The latter would be "easier" (still quite a bit of changes),
but much preferable to me in anyway.

Martin