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" == 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.

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