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

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

>>>>> Duncan Murdoch <murdoch_at_stats.uwo.ca> >>>>> on Thu, 12 Nov 2009 06:36:53 -0500 writes:

    > Martin Maechler wrote:
    >>>>>>> "SF" == Seth Falcon <seth_at_userprimary.net>
    >>>>>>> on Wed, 11 Nov 2009 18:49:12 -0800 writes:
    >>>>>>> 

>>

    SF> On 11/11/09 2:36 AM, Duncan Murdoch 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.
>>
    SF> I would be strongly in favor of a change that provided documentation for     SF> all systems on all systems.
>>
    SF> Since platform specific behavior for R functions is the exception rather 
    SF> than the norm, I would imagine that simply displaying doc sections by 
    SF> platform would be sufficient.

>>
    SF> I think the benefit of being able to see what might not work on another 
    SF> platform far out weighs the inconvenience of finding doc during a search 
    SF> for something that only works on another platform -- hey, that still 
    SF> might be useful as it would tell you what platform you should use ;-)

>>
>> I strongly agree.
>> As someone said, this only applies to relatively few help pages,
>> and I'm not sure if it's worth (at the moment) of first
>> designing a rendering scheme to emphasize your current platform.
>> Maybe even to the contrary, I'd want the PDF version of the
>> help page to (almost (*)) entirely platform independent.
>> It depends how thing *are* platform dependent.
>> If one function argument only applies to Windows, then the
>> corresponding paragraph could simply start,
>> "On Windows, .....".
>> In other situations, using something similar to what Henrik
>> proposed, a \section{..} on platform specific parts would
>> suffice.
>>
    > If that's the intention, there's nothing to stop you from editing the 
    > existing pages.  A quick grep suggests that there are about 100 pages 
    > with #ifdef in the base and recommended packages; 

Yes, I know (did not know the "statistics" here, thanks), but I'd really like us to agree on a slightly changed course of what is desired, rather than the current "#ifdef OS .." parts in the help pages.

The changes can well happen "as time permits". One of the first things would be to somewhat discourage from using "#idef OS" sections in Rd files, in the "Writing R Extensions" manual.

    > there are also a few dozen pages which are completely     > platform-specific (mostly related to Windows API or GUI topics).

I could agree to keep these in man/windows/ and hence not be visible otherwise.
Personally, I'd still much prefer them to be part of the help system also on non-Windows.

    > I suspect the Linux users are going to be the
    > biggest complainers if the Windows-only material starts
    > showing up on their systems.  They don't like to be told
    > they should be using Windows rather than Linux.

The help page would just say that it is Windows-only. That may not at all imply that someone should use Windows.

Martin

    > Duncan Murdoch

>> I also find it very important that I read on "my" (OS) help page,
>> about less or more functionality on another platform, and I'd
>> rather want the full details of that platform than just
>> a note that something is platform dependent.
>> Of course, there's the situation of missing / extra capabilities()
>> but I think these are well documented where applicable, and they
>> *do* follow the idea that you should also learn about things
>> that are currently not available to you.
>>
>> Martin
    >>

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

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