On Mon, 9 Mar 2009, Ben Bryant wrote:
Greetings -
Thanks for the response and apologies for the delay.
I was actually unable to get even the example script for Rd2HTML to work in
2.9.0dev, which may be due to my lack of general programming savvy, or
possibly my working on a windows machine?
So, no information on what went wrong. Your example works for me in
R-devel, even on Windows.
In the meantime I found a workaround to address my immediate needs
(just including another section in the Rd file). The most helpful I
can be with my current level of knowledge is to include a full Rd
text that reproduces the error, if someone would like to give it a
shot. (below).
\value sections are somewhat special. In versions < 2 of Rd format it
starts out as a standard text section but the first \item macro turns
it into a \describe list. And this *is* how they are documented:
'If a list with multiple values is returned, you can use entries of
the form
\item{comp_i}{Description of comp_i.}
for each component of the list returned. Optional text may precede
this list (see the introductory example for rle).'
I take that to mean that text can only *precede* a list. You are
expecting something to work that is AFAICS undocumented and not
intended to work.
In the current Rd2 conversion additional text after \item sections
terminates the list, so this behaves more as you want (as a set of
lists). However, Rd2 conversion is not released as yet, and almost
certainly will not be in 2.9.0. (I don't think the change in
behaviour has yet been agreed by R-core.)
Thanks,
-Ben
%FAKE FUNCTION DOCUMENTATION TO ILLUSTRATE PROBLEM
\name{fake}
\alias{fake}
\title{Fake function documentation}
\description{This is a sample to show a possible bug in the Rd compiler,
which may actually be generally desirable behavior, but behavior that is
encoded in a somewhat opaque way. See the Value section for what is going
on.
}
\usage{
sdprim(x, y = NULL)
}
\arguments{
\item{x}{The usual inputs.}
\item{y}{The usual outputs.}
}
\details{
A good bit of text on the details.
}
\value{
Here I have a paragraph giving the general description of the output form.
Then I have an itemized list describing the elements.
\item{listobject1}{Description of list object 1}
\item{listobject2}{Description of list object 2}
%... etc
\item{lastlistobject}{Description of the last list object}
THEN, here I have a general description of the attributes, and the text
represented by this sentence is what doesn't show up, because it's in
between more of an itemized list.
\item{attribute1}{details of attribute 1}
\item{attribute2}{details of attribute 2}
Then I have text here, and this text does show up.
}
\author{anonymous}
\examples{
#are not too relevant.
}
\keyword{robust}
On Thu, Mar 5, 2009 at 5:49 PM, Duncan Murdoch <murd...@stats.uwo.ca> wrote:
On 05/03/2009 12:29 PM, Ben Bryant wrote:
Greetings -
I am trying to document the "value" section of a function. The function
returns a list, but the list itself also has attributes. I would like to
itemize the list entries, and itemize the attributes, but in between I
would
like to have a sentence or two about the attributes in general. However,
for some reason this intermediate sentence won't show up in the compiled
version, so that it appears the attributes are all just elements in the
returned list. Something is making the assumption that the itemized list
must be uninterrupted, and I don't know the code to tell it not to do
that.
I presume it is a very easy fix, but I haven't been able to get at it.
I pasted some example explanatory Rd code below.
Thanks!
-Ben Bryant
Could you give your example a try in R-devel, with one of the new
conversion functions, e.g. tools::Rd2HTML? I don't think these new
functions are used by default even in R-devel, but if they solve your
problem, there will be less motivation to fix the legacy functions.
Duncan Murdoch
%%%%% Just the Value Section:
\value{
Here I have a paragraph giving the general description of the output form.
Then I have an itemized list describing the elements.
\item{listobject1}{Description of list object 1}
\item{listobject2}{Description of list object 2}
%... etc
\item{lastlistobject}{Description of the last list object}
THEN, here I have a general description of the attributes, and the text
represented by this sentence is what doesn't show up, because it's in
between more of an itemized list.
\item{attribute1}{details of attribute 1}
\item{attribute 2}{details of attribute 2}
Then I have text here, and this text does show up.
}
%%%%
[[alternative HTML version deleted]]
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
[[alternative HTML version deleted]]
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
--
Brian D. Ripley, rip...@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
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
