Re: [Rd] Rd output garbled in some circumstances

From: Duncan Murdoch <murdoch_at_stats.uwo.ca>
Date: Wed, 13 Jan 2010 19:46:35 -0500

On 13/01/2010 6:15 PM, Ross Boylan wrote:
> 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?

I would avoid nesting the \describe within \arguments. Both basically use the same formatting code, and 2.7 probably doesn't support nesting properly. There was no real parser there, just a fallible pattern matching approach.

A better solution is to say your package requires a recent version of R, but maybe that's not feasible for you.

Duncan Murdoch

>
> 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
>
> ______________________________________________
> R-devel_at_r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Thu 14 Jan 2010 - 00:49:39 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Thu 14 Jan 2010 - 09:30:13 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive