Re: [Rd] typo in docs for unlink()
SF == Seth Falcon s...@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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
HenrikB == Henrik Bengtsson h...@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
murd...@stats.uwo.ca wrote:
Henrik Bengtsson wrote:
On Wed, Nov 11, 2009 at 11:36 AM, Duncan Murdoch murd...@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.
Martin
HenrikB At a minimum it is useful to have a note that makes the
HenrikB reader/users/developer aware that the function differ between
HenrikB platforms. (With the new help system, this can be automated if
such
HenrikB functions have been flagged with an attribute, e.g. attr(fcn,
HenrikB differAcrossOSes) - TRUE)
HenrikB Just thoughts.
HenrikB /Henrik
Duncan Murdoch
/Henrik
Duncan Murdoch
-- Tony Plate
Tony Plate wrote:
The VALUE section in the help for 'unlink' says:
| 0| for success, |1| for failure. Not deleting a non-existent file is
not a failure, nor is being unable to delete a directory if |recursive
=
FALSE|. However, missing values in |x| result are regarded as failures.
The last phrase doesn't make sense to me. Should it be either missing
values in x are regarded as failures or missing values in x result in
failure ?
Also, after reading the docs, I'm still unable to work out if unlink()
will return 1 when the user tries to recursively delete a directory on
systems that don't support recursive=T.
The DETAILS section says recursive=TRUE is not supported on all
platforms, and may be ignored, with a warning, which could be
interpreted
as implying no special action when recursive=TRUE is not implemented
(other
than a warning()), and the VALUE section doesn't say what the return
value
will be under such conditions.
I've skimmed the various *_unlink functions in src/main/platform.c, and
it looks like they all implement recursive=TRUE, so I'm still in the
dark
about the required behavior on systems that don't support it. Could
this be
clarified in the help file?
thanks,
Tony Plate
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
Martin Maechler wrote:
SF == Seth Falcon s...@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
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
KH == Kurt Hornik kurt.hor...@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 h...@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
murd...@stats.uwo.ca wrote:
Henrik Bengtsson wrote:
On Wed, Nov 11, 2009 at 11:36 AM, Duncan Murdoch
murd...@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
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
Duncan Murdoch murd...@stats.uwo.ca
on Thu, 12 Nov 2009 06:36:53 -0500 writes:
Martin Maechler wrote:
SF == Seth Falcon s...@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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
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. Duncan Murdoch -- Tony Plate Tony Plate wrote: The VALUE section in the help for 'unlink' says: | 0| for success, |1| for failure. Not deleting a non-existent file is not a failure, nor is being unable to delete a directory if |recursive = FALSE|. However, missing values in |x| result are regarded as failures. The last phrase doesn't make sense to me. Should it be either missing values in x are regarded as failures or missing values in x result in failure ? Also, after reading the docs, I'm still unable to work out if unlink() will return 1 when the user tries to recursively delete a directory on systems that don't support recursive=T. The DETAILS section says recursive=TRUE is not supported on all platforms, and may be ignored, with a warning, which could be interpreted as implying no special action when recursive=TRUE is not implemented (other than a warning()), and the VALUE section doesn't say what the return value will be under such conditions. I've skimmed the various *_unlink functions in src/main/platform.c, and it looks like they all implement recursive=TRUE, so I'm still in the dark about the required behavior on systems that don't support it. Could this be clarified in the help file? thanks, Tony Plate __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
On Wed, Nov 11, 2009 at 11:36 AM, Duncan Murdoch murd...@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. 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.
/Henrik
Duncan Murdoch
-- Tony Plate
Tony Plate wrote:
The VALUE section in the help for 'unlink' says:
| 0| for success, |1| for failure. Not deleting a non-existent file is
not a failure, nor is being unable to delete a directory if |recursive =
FALSE|. However, missing values in |x| result are regarded as failures.
The last phrase doesn't make sense to me. Should it be either missing
values in x are regarded as failures or missing values in x result in
failure ?
Also, after reading the docs, I'm still unable to work out if unlink()
will return 1 when the user tries to recursively delete a directory on
systems that don't support recursive=T.
The DETAILS section says recursive=TRUE is not supported on all
platforms, and may be ignored, with a warning, which could be interpreted
as implying no special action when recursive=TRUE is not implemented (other
than a warning()), and the VALUE section doesn't say what the return value
will be under such conditions.
I've skimmed the various *_unlink functions in src/main/platform.c, and
it looks like they all implement recursive=TRUE, so I'm still in the dark
about the required behavior on systems that don't support it. Could this be
clarified in the help file?
thanks,
Tony Plate
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
Henrik Bengtsson wrote:
On Wed, Nov 11, 2009 at 11:36 AM, Duncan Murdoch murd...@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.
Duncan Murdoch
/Henrik
Duncan Murdoch
-- Tony Plate
Tony Plate wrote:
The VALUE section in the help for 'unlink' says:
| 0| for success, |1| for failure. Not deleting a non-existent file is
not a failure, nor is being unable to delete a directory if |recursive =
FALSE|. However, missing values in |x| result are regarded as failures.
The last phrase doesn't make sense to me. Should it be either missing
values in x are regarded as failures or missing values in x result in
failure ?
Also, after reading the docs, I'm still unable to work out if unlink()
will return 1 when the user tries to recursively delete a directory on
systems that don't support recursive=T.
The DETAILS section says recursive=TRUE is not supported on all
platforms, and may be ignored, with a warning, which could be interpreted
as implying no special action when recursive=TRUE is not implemented (other
than a warning()), and the VALUE section doesn't say what the return value
will be under such conditions.
I've skimmed the various *_unlink functions in src/main/platform.c, and
it looks like they all implement recursive=TRUE, so I'm still in the dark
about the required behavior on systems that don't support it. Could this be
clarified in the help file?
thanks,
Tony Plate
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
On Wed, Nov 11, 2009 at 12:55 PM, Duncan Murdoch murd...@stats.uwo.ca wrote:
Henrik Bengtsson wrote:
On Wed, Nov 11, 2009 at 11:36 AM, Duncan Murdoch murd...@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.
I'd say the union across all OSes should be mentioned under the
\arguments{}. Then one can add to \item{} making it clear that this
is specific to a particular OS, e.g. \item{recursive}{(Unix only)
...}. That is in line with how some arguments are flagged
(optional) in \item{}.
At a minimum it is useful to have a note that makes the
reader/users/developer aware that the function differ between
platforms. (With the new help system, this can be automated if such
functions have been flagged with an attribute, e.g. attr(fcn,
differAcrossOSes) - TRUE)
Just thoughts.
/Henrik
Duncan Murdoch
/Henrik
Duncan Murdoch
-- Tony Plate
Tony Plate wrote:
The VALUE section in the help for 'unlink' says:
| 0| for success, |1| for failure. Not deleting a non-existent file is
not a failure, nor is being unable to delete a directory if |recursive
=
FALSE|. However, missing values in |x| result are regarded as failures.
The last phrase doesn't make sense to me. Should it be either missing
values in x are regarded as failures or missing values in x result in
failure ?
Also, after reading the docs, I'm still unable to work out if unlink()
will return 1 when the user tries to recursively delete a directory on
systems that don't support recursive=T.
The DETAILS section says recursive=TRUE is not supported on all
platforms, and may be ignored, with a warning, which could be
interpreted
as implying no special action when recursive=TRUE is not implemented
(other
than a warning()), and the VALUE section doesn't say what the return
value
will be under such conditions.
I've skimmed the various *_unlink functions in src/main/platform.c, and
it looks like they all implement recursive=TRUE, so I'm still in the
dark
about the required behavior on systems that don't support it. Could
this be
clarified in the help file?
thanks,
Tony Plate
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
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. I would be strongly in favor of a change that provided documentation for all systems on all systems. Since platform specific behavior for R functions is the exception rather than the norm, I would imagine that simply displaying doc sections by platform would be sufficient. I think the benefit of being able to see what might not work on another platform far out weighs the inconvenience of finding doc during a search for something that only works on another platform -- hey, that still might be useful as it would tell you what platform you should use ;-) + seth __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
On 11/11/2009 9:49 PM, Seth Falcon wrote: 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. I would be strongly in favor of a change that provided documentation for all systems on all systems. As I said, I don't think that's hard to implement, but it's hard to design. If you want to put together what the output (say in HTML) should look like for unlink, I'll let you know whether the implementation is really as easy as I think it will be. Duncan Murdoch Since platform specific behavior for R functions is the exception rather than the norm, I would imagine that simply displaying doc sections by platform would be sufficient. I think the benefit of being able to see what might not work on another platform far out weighs the inconvenience of finding doc during a search for something that only works on another platform -- hey, that still might be useful as it would tell you what platform you should use ;-) + seth __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] typo in docs for unlink()
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. -- Tony Plate Tony Plate wrote: The VALUE section in the help for 'unlink' says: | 0| for success, |1| for failure. Not deleting a non-existent file is not a failure, nor is being unable to delete a directory if |recursive = FALSE|. However, missing values in |x| result are regarded as failures. The last phrase doesn't make sense to me. Should it be either missing values in x are regarded as failures or missing values in x result in failure ? Also, after reading the docs, I'm still unable to work out if unlink() will return 1 when the user tries to recursively delete a directory on systems that don't support recursive=T. The DETAILS section says recursive=TRUE is not supported on all platforms, and may be ignored, with a warning, which could be interpreted as implying no special action when recursive=TRUE is not implemented (other than a warning()), and the VALUE section doesn't say what the return value will be under such conditions. I've skimmed the various *_unlink functions in src/main/platform.c, and it looks like they all implement recursive=TRUE, so I'm still in the dark about the required behavior on systems that don't support it. Could this be clarified in the help file? thanks, Tony Plate __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
