[Rd] Writing R-extensions

[Berwin A Turlach]

G'day all,

After reading through "Writing R Extensions", Version 2.1.1
(2005-06-20), I thought the the following points might need
clarifications or corrections.  (I checked that these comments also
hold for "Writing R Extensions", Version 2.2.0.)

1) When I ran "package.skeleton" recently, I noticed that the
   DESCRIPTION file and an entry `type'.  This surprised me a bit
   since I did not remember reading about it in the description of the
   DESCRIPTION file.  I realised that package types are described in
   the last section of Chapter 1 of "Writing R Extensions", but would
   it be possible to add at the end of Section 1.1.1 (The
   `DESCRIPTION' file) something like:

The optional @samp{Type} field specifies the type of the package:
@pxref{Package types}.

2) The description of the `inst' subdirectory states:

        Subdirectories of @file{inst} should not interfere with those
        used by R (currently, @file{R}, @file{data}, @file{demo},
        @file{exec}, @file{libs}, @file{man}, @file{help},
        @file{html}, @file{latex}, @file{R-ex}, and @file{Meta}).

   And I wonder whether this list is incomplete.  Should not, with the
   introduction of localisation, at least @file{po} be listed too?

3) The final sentence in the section on `Registering S3 methods' is:

        Any methods for a generic defined in a package that does not
        use a name space should be exported, and the package defining
        and exporting the method should be attached to the search path
        if the methods are to be found.

   I wonder whether this should actually be:

        Any methods for a generic defined in a package that does not
        use a name space should be exported, and the package defining
        and exporting the generic should be attached to the search path
                          ^^^^^^^
        if the methods are to be found.

   Or is the implication of that sentence that if I have a package
   with a name space which defines a method for a generic defined in
   another package that does not use a name space, then this method
   is only found if my package is attached to the search path and
   mere loading of the namespace is not sufficient?

4) This could be nit-picking (or just the fact that English is not my
   native language), but the section on `Load hooks' states
 
      Packages with name spaces do not use the @code{.First.lib}
      function.  Since loading and attaching are distinct operations
      when a name space is used, separate hooks are provided for each.
      These hook functions are called @code{.onLoad} and
      @code{.onAttach}.
      
   I interpreted this as "o.k., loading and attaching are distinct
   operations, if I load a package .onLoad (and only .onLoad) is run,
   if I attach a package then .onAttach (and only .onAttach) is run".
   But the manual continues a bit further down with

      Packages are not likely to need @code{.onAttach} (except perhaps
      for a start-up banner); code to set options and load shared
      objects should be placed in a @code{.onLoad} function, or use
      made of the @code{useDynLib} directive described next.

   This seems to imply to me that the .onLoad is executed also if I
   attach a package.  So should may understanding rather be "attaching
   a package implies loading it and, hence, if I attach a package,
   then .onLoad and .onAttach are both run (with .onLoad presumably
   run first?)"?

Cheers,

        Berwin