[Rd] typo in docs for unlink()

[Martin Maechler]

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