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

From: Martin Maechler <maechler_at_stat.math.ethz.ch>
Date: Thu, 12 Nov 2009 09:21:58 +0100

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

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 - 08:25:48 GMT

This archive was generated by hypermail 2.2.0 : Thu 12 Nov 2009 - 14:10:27 GMT