[Rd] typo in docs for unlink()

[Martin Maechler]

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