[ESS] Roxygen: arbitrary sections (@section)

[Mathieu Basille]

Dear Henning,

I'm starting to see more clearly now:

Le 31/01/2012 01:12, Henning Redestig a écrit :
> Currently, ESS uses roxygen not roxygen2. It does this silently in the
> background but uses same roxygen installation as you would in the
> associated R buffer. If you see differences in output from 'manual'
> roxygen and when using ESS, you probably have several versions of
> roxygen installed.

After a bit of searching in 'ess-roxy.el', I found the function that was 
actually used by ess-roxy-preview-*: if "myfun.R" is the file with the 
function, the following directly in R gives me the exact same output as 
previously reported (i.e. with the problem of arbitrary sections):

make.Rd.roclet()$parse("myfun.R")

Warning in parse.warning(key, "is an unknown key") :
   @section is an unknown key.
[...]

I guess it means that this is a roxygen problem, not an ESS one...

> I think ESS can safely move to roxygen2 since
> roxygen2 appears backwards compatible with roxygen.

I'm sorry I could not find what was the syntax with roxygen2 (it probably 
implies 'rd_roclet', but wasn't able to find the correct use of it on a 
simple function). Can not say if the use of @section is fixed in roxygen2, 
but it probably does not matter. As roxygen is no longer supported, it is 
still better to switch to roxygen2 anyway...

> Will fix this in the near future unless someone beats me to it.

Great to hear! :)

> and yes you can have both svn-version and released ESS installed (not
> so much of an installation as just a folder with lisp code) but you
> need to specify in your .emacs which version you want to load.

Thanks for this. I understand that there is no code yet, but please let me 
know if you start working on this and need testers, I'll be happy to try it 
out!

Best,
Mathieu.


> 2012/1/30 Mathieu Basille<basille at ase-research.org>:
>> Dear Martin,
>>
>> Thanks for your answer.
>>
>> Le 30/01/2012 16:49, Martin Maechler a écrit :
>>
>>> 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 ..).
>>
>>
>> Well, it did prove something: that I didn't quite understand the whole
>> Roxygen stuff. I think you fixed it, thanks!
>>
>>
>>> 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)
>>
>>
>> Do I understand correctly that one should now use roxygen2, which requires
>> the development version of ESS? And that current stable ESS (5.14) can not
>> deal with roxygen2, but only roxygen?
>>
>> I have basically no knowledge of Lisp programming, but please let me know if
>> I can be of any help here. Shall I start using and testing ESS-dev with
>> roxygen2? Is it possible to keep both ESS-stable and ESS-dev on the same
>> computer?
>>
>> Sorry for the many (and probably dumb) questions, I feel pretty useless
>> here...
>>
>> Best,
>> Mathieu.
>>
>>
>>
>>> 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
>>>>
>>
>> --
>>
>> ~$ 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
>
>
>

-- 

~$ 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.