From ross at biostat.ucsf.edu  Thu Jan 14 00:15:36 2010
From: ross at biostat.ucsf.edu (Ross Boylan)
Date: Wed, 13 Jan 2010 15:15:36 -0800
Subject: [Rd] Rd output garbled in some circumstances
Message-ID: <1263424536.6304.69.camel@corn.betterworld.us>

I'm having trouble getting correct help output in some circumstances for
a package I've created. Though this is not an issue with the current R,
I would like my package to work with previous ones as well.

I'm looking for suggestions about how I could rework my .Rd file so that
it will work with prior R's.  In particular, R 2.7 is in the latest
stable release of Debian, so I'd like to solve the problem for 2.7.

The .Rd file is for a function and has an arguments section like this
\arguments{
  \item{formula}{ A formula giving the vectors containing
## skipped
    covariates.  }
## skipped
  \item{stepdenominator}{See \code{stepnumerator} just above.}
  
  \item{do.what}{\describe{
    \item{1}{By default, calculates a maximimum likelihood.  To evaluate
      a single likelihood, set all parameters to fixed. }
    \item{0}{Count number of paths and related statistics without
      evaluating the likelihood.}
    \item{-1}{Get detailed counts (but no likelihoods) associated with
      each case.  The return value is a matrix.}
    \item{10}{Use the model to generate a random path for each
      case. returning a \code{data.frame} with simulated observed states
      and times and all other data as observed.}
    }}

  \item{testing}{This argument is  only for use by developers.  Set it
## etc

This comes out fine in a pdf, but ?mspath (the function) produces, in
part,
<quote>
stepdenominator: See 'stepnumerator' just above.

     1 By default, calculates a maximimum likelihood.  To evaluate a
          single likelihood, set all parameters to fixed. 

     0 Count number of paths and related statistics without evaluating
          the likelihood.
</quote>
in R 2.7.  The "do.what" header has vanished.  In R 2.10 it's fine.

Is there an error in my documentation format?
Even if not, is there some change I could make that would get R 2.7 to
work better?

The R change log doesn't show anything obviously related to this, though
it has several references to unspecified fixes to the documentation
system.  I also tried looking at the bug tracker, but couldn't find
anything--in fact I had trouble identifying bugs in the documentation
system as opposed to bugs in the documentation.

Thanks.
Ross Boylan



[Rd] Rd output garbled in some circumstances
Ross Boylan