help files for load and related functions

Dear Patrick,

?Firstly, and most importantly, I do not think that your post qualified
for Rd! Please use the correct mail list for such things: R-help. I do
not think anybody on Rd wants mailboxes ?clogged with irrelevant
messages.

Back to your question: it is not clear if you are confused, or your
'user' is confused, but all three help pages look pretty clear and
straight forward to me. Moreover,  I do not see any connection between
attach and library, which you find logical:

- load - the general use of this one is to load external data sets, e.g.
load serialised R object(s) (as the example shows). Until you load, you
cannot use the object as it has no relation to the R session and can be
e.g. a file sitting somewhere on a network

- attach - the general use of this one would be to access elements of a
data set directly, without the data set name specifier and the accessor
operator, such as $, thus as the help page states - it is used to add
the data set to the search path (as the example shows). If you look at
the example, you do not have to call attach to be able to use data, data
could have existed there before and what you effectively get with attach
is a more convenient way of dealing with the data

- library - is used to load *and* attach an R package, which is not
exactly the same as a serialised R object(s), but a full set of other
functionality. Attaching packages is just a part of the loading process,
which occurs basically when the package becomes visible to the user.
Same as with load, you cannot use the package until you load it. There
is not a hint of similarity between loading a package and attaching a
data set as I see it. 

Regards,
Oleg

On Mon, 2007-12-17 at 11:00 +0000, Patrick Burns wrote:

I recently had a discussion with a user about loading
and attaching in R.  I was surprised that the help files
don't  provide a very clear picture.

 From my point of view 'load' and 'attach' are very
similar operations, the difference being that 'attach'
creates a new database on the search list while 'load'
puts all the objects into the global environment.

The help file for 'load' is inexplicit that this is what
happens.  The 'load' and 'attach' help files neither refer
to the other in their See Also.

Furthermore, the 'library' help file talks about "loading"
packages.  I would suggest that it should use "attaching"
as that is the analogous operation.

None of these three help files (nor that of 'save') has a
Side Effects section.  Personally I think that all help files
should have a Side Effects section (to make it clear to
new users what side effects are and that they are not a
good thing for most functions to have).  I can understand
there could be another point of view on that.  However, I
definitely think that there should be a Side Effects section
in the help files of functions whose whole point is a side
effect.

Patrick Burns
patrick at burns-stat.com
+44 (0)20 8525 0696
http://www.burns-stat.com
(home of S Poetry and "A Guide for the Unwilling S User")