Skip to content

In Rd: \describe \itemize and \item

5 messages · Nicholas L Crookston, Duncan Murdoch

Original
Nicholas L Crookston
# 
I rebuilt a test version of my yaImpute package using Uwe Ligges' windows 
build service. 
I got this reply: Check result: OK
R version 2.9.0 Under development (unstable) (2009-01-27 r47756)

Here is the issue: I have the following construct in help files (this 
example relates to "data"):

\format{
  A data frame with 847 rows and 29 columns: \cr\cr
  Ground based measurements of trees (Y-variables):
  \itemize{
     \item{TopHt}{Height of tallest trees (ft)}
     \item{LnVolL}{Log of the volume \eqn{(ft^3/acre)} of western larch}
 ...... many lines deleted ......
     \item{LnVolPP}{Log of the volume \eqn{(ft^3/acre)} of ponderosa pine}
     \item{CCover}{Canopy cover (percent)}
  }
  Geographic Location, Slope, and Aspect (X-variables):
  \itemize{
    \item{utmx}{UTM easting at plot center}
    \item{utmy}{UTM northing at plot center}
...... many lines deleted ......
    \item{elevm}{Mean elevation (ft) above sea level over plot}
    \item{slpsinaspm}{Mean of slope (proportion) times the sine of aspect}
  }
...... many lines deleted ......
}

What I get in the help file is:
=========================
Format  <this word is set in bold, correctly>
A data frame with 847 rows and 29 columns: 

Ground based measurements of trees (Y-variables): 

   TopHt 
      Height of tallest trees (ft) 
   LnVolL 
      Log of the volume (ft^3/acre) of western larch 
========================= ......and so on........
[I've inserted 3 spaces to mimic tabs in this illustration]

I would expect (and I used to get) something like this:
=========================
Ground based measurements of trees (Y-variables): 

 <bullet here>  TopHt   Height of tallest trees (ft) 
 <bullet here>  LnVolL  Log of the volume (ft^3/acre) of western larch 
=========================

Note that in version 2.6.2 (under SuSE 10.3) this code fails the check, 
but my original code worked. 

The entire issue came up in reference to Kurt Hornik's recent mail that we 
get our help files ready for the next release of R. 

My current production help files work, but do not comply with the 
instructions as I understand them and fail the check on the development 
versions. I'm not sure I have fixed them correctly, but I'm trying!

Suggestions?  Comments?

Thanks, Nick.

PS: If this Email is not simple text, please let me know.

Nicholas L. Crookston, Operations Research Analyst
Rocky Mountain Research Station
USDA Forest Service
1221 South Main, Moscow, ID 83843
Office: (208) 883-2317, FAX: (208) 883-2318
EMail: ncrookston at fs.fed.us
Duncan Murdoch
#
On 29/01/2009 5:22 PM, Nicholas L Crookston wrote:
I think we need more info to comment on.  Is this file one of the ones 
in the yaImpute package on CRAN, or is it unreleased?  Is the Rd file 
available for us to look at?  Does the man page look different in 2.8.1 
from what you expect (there haven't been serious changes there), or only 
in R-devel (2.9.0)?  2.6.2 is pretty old, but I don't think any of the 
requested changes should be incompatible with it.

Duncan Murdoch
Nicholas L Crookston
# 
Duncan Murdoch <murdoch at stats.uwo.ca> wrote on 01/29/2009 07:14:11 PM:
windows
larch}
pine}
aspect}
The problem is in an unreleased version built in the development 
environment.
The entire unreleased package can be found at this temporary location: 
http://forest.moscowfsl.wsu.edu/gems/yaImpute_1.0-8.tar.gz

The original is on CRAN (version 1.0-7). It worked under the old parser, 
but
not using parser 2 (the warnings on CRAN point to the problem). 
You can see the difference by looking at TallyLake.Rd 
in the two versions. I would be happy to send you just these files if 
you'd 
like me to.

Note that text version of the help file builds as I expect it to. 
The problem is in the htlm version.

PS: I tried two versions of \items 
    \item{utmx}{UTM easting at plot center}
and 
    \item{utmx   }{UTM easting at plot center}
(note added spaces, added for readability of the Rd file 
this difference does not seem to matter.)

Thanks, Nick
Duncan Murdoch
#
On 1/30/2009 2:22 PM, Nicholas L Crookston wrote:
Okay, I think I see now.  I installed your package version 1.0-8 in 
R-devel (to be 2.9.0), and the ?TallyLake man page looks fine to me in 
text mode, looks slightly funny in HTML (with the labels one line above 
the thing they're describing).  But to me it looks better in the new 
HTML than version 1.0-7 looked in 2.8.1:  in that version, there was no 
attempt to line up the descriptions to a common left margin, so they 
tended to be confused with the thing they were describing.

So I'm not sure what you'd really like to see in the output.  Can you 
describe it again?

Duncan Murdoch
Nicholas L Crookston
# 
Duncan Murdoch <murdoch at stats.uwo.ca> wrote on 01/30/2009 12:04:56 PM:
Reading from the R-exts.pdf, section 2.4:

"The \itemize and \enumerate commands take a single argument, within which 
there may be
one or more \item commands. The text following each \item is formatted as 
one or more paragraphs,
suitably indented and with the first paragraph marked with a bullet point 
(\itemize)
or a number (\enumerate)."

I'm using \itemize so I expect to see a bullet point making the first 
paragraph of each item.

What I'm getting is what you would expect with the \describe command, as 
described here:

"The \describe command is similar to \itemize but allows initial labels to 
be specified.
The \items take two arguments, the label and the body of the item, in 
exactly the same way
as argument and value \items. \describe commands are mapped to <DL> lists 
in HTML and
\description lists in LATEX."
Nick Crookston