.BG
.FN library
.FN library.dynam
.TL
Shared Functions and Datasets
.CS
library(section, first=FALSE, help)
library.dynam(section, file)
.AG section
character string or name giving the name of a section of
the library.
.AG first
if `TRUE', the data directory for this section is attached
before the system functions and data, in position 2 of the
search list; otherwise it is attached at the end of the search list.
.AG help
optional character string or name of a section on which help is desired.
Help for a section gives (at least) a list of objects with brief
descriptions.
Once a section has been attached, the `help' function can be
used to get detailed documentation on particular objects in the
section.
.AG file
character name of a file to be dynamically loaded
(not a full pathname).
.PP
If no arguments are given to `library', a brief description
of each available section is printed.
.PP
`library.dynam' is meant to be used 
by functions
that are part of a library section
to dynamically load object code.
If the corresponding object code has not been loaded in this session, it
constructs the correct path name for the
code and calls `dyn.load'.
Using `library.dynam' in functions in the library ensures that code is not
loaded unnecessarily.
.PP
When S is shipped, the library always contains sections named
.Co examples 
and
.Co semantics .
These correspond to many of the example functions used
in the S book (see the index under
.Co examples ).
To try one of the functions given in this book
that is not a standard part of S,
do `library(examples)' and look for it there.
.PP
The functions and data objects accessed by `library' 
are often user-contributed
and are not an official part of S.
They should be used with caution.
.PP
A library section corresponds to
a directory inside the `library' subdirectory
of the S home directory.
For example, if the S home directory is `/usr/s', then the `examples'
section corresponds to directory `/usr/s/library/examples'.
Within each section, there must be a `.Data' directory with a `.Help' subdirectory
containing, respectively, the objects and their documentation.
There must be also a file named `README' that gives the overall
description of the section.
If there are C or Fortran routines whose
object code is to be dynamically loaded
by functions in the section, their source code and object files
should also reside in the section directory.
Any dynamic loading should be carried out through the `library.dynam' function.
When source code is present, there should also be a `makefile'
that makes the required object files.
The library-level `README' file (`/usr/s/library/README')
contains the one-line descriptions of the sections of the library, and
should be updated whenever a new section is added to the library.
Library sections may be symbolic links to
user-owned portions of the file system.
.SE
These functions are used for their side effects: `library' prints
documentation or attaches a data directory.
The `library.dynam' function ensures that object code has been dynamically
loaded.
Objects `lib.loc' and `section.file' are created in frame 0.
.SA
`attach', `dyn.load', `help'.
.EX
library()   # print list of sections
library(help="examples")  # documentation on examples section
library(examples)  # attach examples data directory
library.dynam("examples","quantum.o")
.KW data
.WR
