[Rd] Re: [R] Package Documentation, cryptic

[Prof Brian Ripley]

[Moved to R-devel: please check the posting guide.]

On Tue, 9 Nov 2004, Christian Hoffmann wrote:

Asking why things that are not documented do not work is unproductive, I 
believe.  Instead please tell us why you are not using the standard 
procedures.

> ------- Question:
> B) In which sections of *.Rd is LaTeX notation allowed, where *not*?

Only where documented, namely inside the first argument of \eqn{} and
\deqn{}, AFAIR.

> The relevant code snippets:
> /CWHstat/man/my.table.margin.Rd:
> \name{my.table}
> \alias{my.table.margin}
> \usage{
> my.table.margin(v,w)
> my.table.margin(m)
> }
> \arguments{
>    \item{v, w}{Factors.}
>    \item{m}{Matrix.}
> }
> 
> /CWHstat/man/my.table.margin.r:
> my.table.margin <- function(v, w) {
>        if (missing(w)) tab <- v else tab <- table(v, w)
> 
> C) ------- Question:
> How can I document this type of behaviour of polyvalent parameters 
> without "check" baulking at me?

The argument is `v': documenting it as `m' is incorrect.  You need

  \item{v}{factor or matrix.}
  \item{w}{factor.}

or better make `my.table.margin' generic with factor and matrix methods
(but still agreeing on their first argument).

> hoffmacw at fluke:~/R/Sources >cd CWHstat.Rcheck
> hoffmacw at fluke:~/R/Sources/CWHstat.Rcheck >cp ../Rd.sty .
> 
> E) *comment* copy is necessary, because each run of check destroys old 
> directory *.Rcheck, Is there a way around this? I cannot write to 
> $R_HOME/share.

Why do you need Rd.sty in there?  It works for 416 packages on CRAN with 
no such copy.  That's the cause of F), as you are trying to overwrite R's 
Rd.sty -- why?

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595