[Rd] Chunk of text won't show up when compiling Rd file

[Prof Brian Ripley]

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 <murdoch at 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 at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>
>>
>>
>
> 	[[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

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