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

[Laurent Gatto]

On 1 October 2010 23:01, Vinh Nguyen <vqnguyen at uci.edu> wrote:
> 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?

Not really sure if that would be useful.

> 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.

Yes, use NULL at the end of the packagename-package chunk.
I really think that adding roxygen as a dependency would be suboptimal.
Note that I can reproduce the error with roxygen() -- sessionInfo below.

>>> 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!
>

> sessionInfo()
R version 2.13.0 Under development (unstable) (2010-09-19 r52946)
Platform: x86_64-unknown-linux-gnu (64-bit)

locale:
 [1] LC_CTYPE=en_GB.utf8       LC_NUMERIC=C
 [3] LC_TIME=en_GB.utf8        LC_COLLATE=en_GB.utf8
 [5] LC_MONETARY=C             LC_MESSAGES=en_GB.utf8
 [7] LC_PAPER=en_GB.utf8       LC_NAME=C
 [9] LC_ADDRESS=C              LC_TELEPHONE=C
[11] LC_MEASUREMENT=en_GB.utf8 LC_IDENTIFICATION=C

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base

Note: locally installed roxygen is a modified svn version.