From gavin.simpson at ucl.ac.uk  Fri Aug  3 15:28:56 2007
From: gavin.simpson at ucl.ac.uk (Gavin Simpson)
Date: Fri, 03 Aug 2007 14:28:56 +0100
Subject: [Rd] correct Rd markup for \value{}
Message-ID: <1186147736.30885.80.camel@gsimpson.geog.ucl.ac.uk>

Dear DevelopeRs

Several functions in a package of mine have complex returned objects
that are lists within the returned list. I wish to document each of the
components of these sublists.

If I do this within a \value{} section and nest \item within an existing
\item, I get indented R-help sections in the standard help view (eg as
shown by ?foo in Linux), but not in the PDF.

For example:

\item{model}{a list containing the model or non-bootstrapped
    estimates for the training set. With the following components:
      \item{\code{estimated}}{estimated values for \code{"y"}, the
	environment.}
    }
  }

If I add an \itemize (for example:

\item{model}{a list containing the model or non-bootstrapped
    estimates for the training set. With the following components:
    % added \itemize
    \itemize{
      \item{\code{estimated}}{estimated values for \code{"y"}, the
	environment.}
    }
  }

) then these are indented in both the ?foo help and the pdf.

But this has several niggles;:

     1. that the indented \item labels are not left aligned as the top
        level \items are, 
     2. as shown above, I have to manually wrap the labels in \code{ }
        to have them show in typewriter font in the pdf pages (but then
        these appear underlined and wrapped in ' ' in the standard view
        in the terminal), and
     3. that in the standard help viewer in the terminal, I don't get
        the ":" after the sub item labels.

I suspect I'm missing something or trying to do something that is not
possible without the niggles.  I'd appreciate suggestions as to where
I'm going wrong, what documentation I missed or suggestions based on the
experience of others.

Thanks in advance,

G

> version
               _
platform       i686-pc-linux-gnu
arch           i686
os             linux-gnu
system         i686, linux-gnu
status         Patched
major          2
minor          5.1
year           2007
month          07
day            05
svn rev        42131
language       R
version.string R version 2.5.1 Patched (2007-07-05 r42131)

-- 
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
 Gavin Simpson                 [t] +44 (0)20 7679 0522
 ECRC, UCL Geography,          [f] +44 (0)20 7679 0565
 Pearson Building,             [e] gavin.simpsonATNOSPAMucl.ac.uk
 Gower Street, London          [w] http://www.ucl.ac.uk/~ucfagls/
 UK. WC1E 6BT.                 [w] http://www.freshwaters.org.uk
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%



[Rd] correct Rd markup for \value{}
Gavin Simpson