[Roxygen-devel] DESCRIPTION file generation + roxygen() error + multiple keywords

[Vinh Nguyen]

On Fri, Oct 1, 2010 at 2:49 PM, Laurent Gatto <laurent.gatto at gmail.com> wrote:
> On 1 October 2010 00:39, Vinh Nguyen <vqnguyen at uci.edu> wrote:
>> get transcribed into the DESCRIPTION file at all?  Example:
>>
>> #' Tests pseudoprimality by Fermat's little theorem.
>> #'
>> #' \tabular{ll}{
>> #' Package: \tab pseudoprime\cr
>> #' Type: \tab Package\cr
>> #' Version: \tab 0.1\cr
>> #' Date: \tab 2008-08-24\cr
>> #' License: \tab GPL (>= 2)\cr
>> #' LazyLoad: \tab yes\cr
>> #' }
>> #'
>> #' Using the Fermat primality test, pseudoprime checks for primes
>> #' probabilistically; the test is fooled every time by Carmichael
>> #' numbers.
>> #'
>> #' \code{\link{is.pseudoprime}} checks a number \code{n} for
>> #' pseudoprimality, applying Fermat's test \code{times} times.
>> #'
>> #' @name pseudoprime-package
>> #' @aliases pseudoprime
>> #' @docType package
>> #' @title Tests pseudoprimality by Fermat's little theorem
>> #' @author Peter Danenberg \email{pcd@@roxygen.org}
>> #' @references
>> #' \url{http://en.wikipedia.org/wiki/Fermat's_little_theorem}
>> #' @keywords package
>> #' @seealso \code{\link{is.pseudoprime}}
>> #' @examples
>> #' is.pseudoprime(13, 4)
>> roxygen()
>>
>> The tabular part seems to go into a DESCRIPTION file.  Is there a way
>> (or plans) to update the DESCRIPTION file based on this chunk?  Am I
>> missing something?  I think having this piece of information in one
>> place as opposed to two is easier on the maintainer.
>
> The package documentation (i.e man/packagename-package.Rd) and the
> DESCRIPTION file are different beasts. In general, I don't think that
> package documentation stuff is meant to be added to the DESCRIPTION
> file. As far as I know, roxygen does update the DESCRIPTION file's
> Collate field, but I think that's all. I could not reproduce the
> update of the DESCRIPTION file based on the tabular information when
> running R CMD roxygen.
>

I see.  Guess that tabular piece from the vignette isn't really
necessary for packagename-package.Rd; I thought it was based on the
vignette.  I'll just keep a separate DESCRIPTION file then.

So what does everyone think on extending roxygen to generate the
DESCRIPTION by documenting it in the packagename-package chunk?  Good
idea or bad?

I guess what I'm envisioning is having ONE .R file that can generate
an entire package (most files, except .C, etc: .R, .Rd, DESCRIPTION).

>> 2.  I get an error saying roxygen() is not found when running R CMD
>> check after roxygenize().  Should we always specify that our package
>> depends on roxygen in order for it to pass this?  roxygen() is in the
>> .R file after running package.skeleton() and roxygenize().
>
> You could also change roxygen() by NULL at the end of the file. This
> should fix your issue, but I don't know what the error you describe
> means and why it is returned. Anyway, there shouldn't be any
> requirement to specify roxygen as a dependency.
>

In the example above, roxgen() is called after the packagename-package
chunk (that updates packagename-package.Rd) after running
roxygenize().  When we run R CMD check on the package directory, I get
an error that roxygen() is not found -- because the roxygen library is
not loaded.

Are you suggesting I use NULL instead of roxygen() after the
packagename-package chunk?  Or should I set the DESCRIPTION file to
depend or require the roxygen package.

>> 3  How should multiple keywords be spelled out in the documentation
>> chunk?  Commas didn't work for me.  One word per @keywords tag?
>
> Several keywords separated by a space:
> @keywords keyword1 keyword2
>

Thanks.  Guess it is space delimited and we can't have keywords with spaces.

> Hope this helps.
>
> Best wishes,
>
> Laurent

Thanks so much!