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

From: Martin Maechler <maechler_at_stat.math.ethz.ch>
Date: Thu, 12 Nov 2009 15:00:14 +0100

>>>>> "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@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) :

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

Martin



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Thu 12 Nov 2009 - 14:04:47 GMT

This archive was generated by hypermail 2.2.0 : Thu 12 Nov 2009 - 14:50:24 GMT