From murdoch at stats.uwo.ca  Thu Nov 12 12:36:53 2009
From: murdoch at stats.uwo.ca (Duncan Murdoch)
Date: Thu, 12 Nov 2009 06:36:53 -0500
Subject: [Rd] typo in docs for unlink()
In-Reply-To: <19195.50598.636144.927120@lynne.math.ethz.ch>
References: <4AFA350D.7060303@acm.org>	<4AFA3AA7.8080104@acm.org>	<4AFA93B1.6050508@stats.uwo.ca>	<4AFB77A8.30802@userprimary.net>
	<19195.50598.636144.927120@lynne.math.ethz.ch>
Message-ID: <4AFBF355.5010803@stats.uwo.ca>

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; there are also a few 
dozen pages which are completely platform-specific (mostly related to 
Windows API or GUI topics).   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.

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
>



[Rd] typo in docs for unlink()
Duncan Murdoch