[Rd] help files for load and related functions

[Gavin Simpson]

On Mon, 2007-12-17 at 14:06 +0000, Oleg Sklyar wrote:
> 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.

No. R Devel *is* the correct place for this discussion, as it pertains
to the development of R. Patrick is reporting that he found the current
help for load(), attach() etc lacking explicit statements about what R
actually does when you call them, and how the functions differ in their
side effects, especially from the point of view of a new "user".

The reason for your comment above is perhaps related to the one below my
text; Patrick _isn't_ looking for help, just pointing out an infelicity
in the current documentation as identified by the "user", and, I
suspect, welcoming comment on his suggestions for changes.

G

> 
> 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")
> > 
> > ______________________________________________
> > R-devel at r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel
-- 
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
 Dr. Gavin Simpson             [t] +44 (0)20 7679 0522
 ECRC, UCL Geography,          [f] +44 (0)20 7679 0565
 Pearson Building,             [e] gavin.simpsonATNOSPAMucl.ac.uk
 Gower Street, London          [w] http://www.ucl.ac.uk/~ucfagls/
 UK. WC1E 6BT.                 [w] http://www.freshwaters.org.uk
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%