[ESS] Roxygen: arbitrary sections (@section)

[Martin Maechler]

On Mon, Jan 30, 2012 at 18:40, Mathieu Basille <basille at ase-research.org> wrote:
> Hello,
>
> I'm new to the use of Roxygen with Emacs (actually new to writing
> documentation at all!), so please apologize if it is a dumb question. I'd
> like to add non-standard sections associated to the documentation. Using the
> example of ESS doc [1], say I'd like to add a section 'Bli' with the content
> 'blabla'. The Roxygen manual [2] recommend to use:
>
> "@section Name: contents Use to add to an arbitrary section to the
> documentation. The name of the section will be the content before the first
> colon, and the contents will be everything after the colon."
>
> Let's do so:
>
> ##' Description of the function
> ##'
> ##' Further details about this function
> ##' @title A title
> ##' @param me all parameters must be listed and documented
> ##' @return Description of the return value
> ##' @author The author
> ##' @section Bli: blabla
> myfun <- function(me)
>    cat("Hello", me, "\n")
>
> Previewing the Rd file (C-c C-e C-r) results in:
>
> Warning in parse.warning(key, "is an unknown key") :
>  @section is an unknown key.
> \name{myfun}
> \alias{myfun}
> \title{A title}
> \usage{myfun(me)}
> \description{Description of the function}
> \details{Further details about this function}
> \value{Description of the return value}
> \author{The author}
> \arguments{\item{me}{all parameters must be listed and documented}}
>
> It seems that the @section is unknown to the Roxygen package for ESS. It
> works, however, if I directly use the Roxygen package for R. I first save
> the following myfun.Rd file:
>
> \name{myfun}
> \alias{myfun}
> \title{A title}
> \usage{myfun(me)}
> \description{Description of the function}
> \details{Further details about this function}
> \value{Description of the return value}
> \author{The author}
> \arguments{\item{me}{all parameters must be listed and documented}}
> \section{Bli}{blabla}
>
> And then convert it to help text:
>
> ===================== R =========================
> library(tools)
> Rd2txt("myfun.Rd")
>
> A title
>
> Description:
>
>     Description of the function
>
> Usage:
>
>     myfun(me)
>
> Arguments:
>
>      me: all parameters must be listed and documented
>
> Details:
>
>     Further details about this function
>
> Value:
>
>     Description of the return value
>
> Bli:
>
>     blabla
>
> Author(s):
>
>     The author
> ===================== R =========================

The last part of the above does not prove anything: Of course an *.Rd file
with a \section{..}{..} is correctly converted to text (or latex or html or ..).
That is all in R's     R CMD Rdconv ...
and entirely unrelated to anything Emacs, ESS, or Roxygen.

But your point is ... rightly so ... that the @section  Roxygen entry
is not translated
to *.Rd using R's current functionality,
which builds on using the 'roxygen' package.

I guess that it nowadays should start using the 'roxygen2' package instead
(and let's hope that that does not require and load many more packages).
OTOH, roxygen2 is not API compatible to 'roxygen', so just replacing
it may not quite be sufficient.
...

For the moment, and from my point:

"patches are welcome"
(the current source is available via  svn (subversion) or a web browser from
 https://svn.r-project.org/ESS/trunk/lisp/
 and yes, the patch *MUST* be against the current source (modulo 1--3 days)

Martin


> Is there anything I can do to be able to use @section in Roxygen
> documentation using Emacs?
>
> Note: I use ESS 5.14 with Emacs 23.2.1 under Debian Stable, with R 2.14.1
> and roxygen package for R 0.1-3.
>
> Sincerely,
> Mathieu Basille.
>
>
> [1] http://ess.r-project.org/Manual/ess.html#Roxygen
>
> [2] http://roxygen.org/roxygen2-manual.pdf
>
> --
>
> ~$ whoami
> Mathieu Basille, Post-Doc
>
> ~$ locate
> Laboratoire d'Écologie Comportementale et de Conservation de la Faune
> + Centre d'Étude de la Forêt
> Département de Biologie
> Université Laval, Québec
>
> ~$ info
> http://ase-research.org/basille
>
> ~$ fortune
> ``If you can't win by reason, go for volume.''
> Calvin, by Bill Watterson.
>
> ______________________________________________
> ESS-help at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/ess-help
>