[ESS] Roxygen: arbitrary sections (@section)

[Mathieu Basille]

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


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.