Re: Re: [babel] Writing R-packages the org way?

From: "Charles C. Berry" <cberry@tajo.ucsd.edu>
To: Dan Davison <davison@stats.ox.ac.uk>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>,
	Rainer M Krug <r.m.krug@gmail.com>
Subject: Re: Re: [babel] Writing R-packages the org way?
Date: Thu, 7 Oct 2010 21:29:59 -0700	[thread overview]
Message-ID: <Pine.LNX.4.64.1010071949470.29985@tajo.ucsd.edu> (raw)
In-Reply-To: <87pqvlncsk.fsf@stats.ox.ac.uk>

On Thu, 7 Oct 2010, Dan Davison wrote:

> Rainer M Krug <r.m.krug@gmail.com> writes:
>
>> On Thu, Oct 7, 2010 at 5:12 PM, Erik Iverson <eriki@ccbr.umn.edu> wrote:
>>> Dan Davison wrote:
>>>> Erik Iverson <eriki@ccbr.umn.edu> writes:
>>>>  Rainer M Krug wrote:
>>>>>
>>>>>> Hi
>>>>>>
>>>>>> I am about to write an R package, and as I am an org-mode and
>>>>>> org-babel user, I would (obviously) like to use org-mode for that.
>>>>>>
>>>>>> Is there a recommended way of writing an R package in org-babel, or
>>>>>> do I have effectively wrap the R code for the documentation
>>>>>> etc. into source blocks in babel?
>>>>>>
>>>>> That's what I do.  I've looked into converting an org-file to
>>>>> Roxygen or Rd markup, but never got very far.  My idea at the time
>>>>> was to do something like:
>>>>>
>>>>> * function1
>>>>> ** Help
>>>>> *** Title
>>>>>    this is function 1 title
>>>>> *** Description
>>>>>    function1 does this...
>>>>> *** Usage
>>>>>    function1(arg1, arg2, ...)
>>>>> *** Arguments
>>>>>    arg1: the first argument
>>>>> *** Examples
>>>>>    function1(arg1 = x, arg2 = y)
>>>>> **Definition
>>>>>    begin_src R :tangle R/package.R
>>>>>    function1 <- function(arg1, arg2) {
>>>>>
>>>>>    }
>>>>>
>>>>>
>> I like the idea of a kind of template, which takes the function name as a
>> parameter and expands it to the above described structure, but also
>> including one section for tests.
>> That would definitely be a starting point from which one could look into the
>> "problem" of the .Rd files. As I am not an emacs / elisp expert, how could
>> that be done (the template)?
>
> Something like this?
>
> --8<---------------cut here---------------start------------->8---
> #+function: R-pkg-template(function_name)
> #+begin_src sh :results output org
> cat << EOF
> * $function_name
> ** Help
> *** Title
>    this is $function_name title
> *** Description
>    $function_name does this...
> *** Usage
>    $function_name(arg1, arg2, ...)
> *** Arguments
>    arg1: the first argument
> *** Examples
>    $function_name(arg1 = x, arg2 = y)
> ** Definition
>    begin_src R :tangle R/package.R
>    $function_name <- function(arg1, arg2) {
>
>    },

> EOF
> #+end_src
> --8<---------------cut here---------------end--------------->8---
>

I'm late to this party, but thought I might add a few bits. I think
keeping package maintenance and development in emacs makes perfect
sense, but I am less certain about using a single org file.

ESS already has Rd-mode, which has helpful functions like

     Rd-mode-insert-skeleton
and
     Rd-preview-help

Rather than store the Rd markup or something that gets translated to
it (BTW, see http://developer.r-project.org/parseRd.pdf) in a src
block, I'd make a skeleton package directory and just store links to
the man/*.Rd files within my *.org file and visit them from there.

In the *.org file I'd put src blocks to run R CMD check and R CMD
INSTALL like this:

#+begin_src sh :results outout
    R_ARCH=/x86_64
    export R_ARCH
    R CMD check  makeSitesDF/  | sed 's/^/ /'
  #+end_src

for example which helps me keep track of my progress and keeps me from
accumulating junk in a terminal window. R src blocks can be used to
run test code or to develop and try out a function before moving it to
R/*.R. I've done just enough of this kind of stuff to feel that
starting with an org file and a package directory skeleton that is
slowly populated works for me as a way to get off the ground with new
packages.

However, my $0.02 is that a lot of functionality would need to be
added to make a single org file serve as an all purpose package
development and maintenance environment.

If you do decide to go all in for a 'one org file makes one package'
approach, you might try to get Rd language support added, so you can
edit Rd directly in an Org Src buffer in Rd-mode. And get
org-babel-Rd-evaluate to run Rd-preview-help or call Rd2HTML or
whatnot.

HTH,

Chuck

> Then, to insert a template, you can use
>
> #+call: R-pkg-template(function_name="do.something") :results output org raw
>
> which should give something like this:
>
> --8<---------------cut here---------------start------------->8---
> #+results: R-pkg-template(function_name="do.something")
> * do.something
> ** Help
> *** Title
>    this is do.something title
> *** Description
>    do.something does this...
> *** Usage
>    do.something(arg1, arg2, ...)
> *** Arguments
>    arg1: the first argument
> *** Examples
>    do.something(arg1 = x, arg2 = y)
> ** Definition
>    begin_src R :tangle R/package.R
>    do.something <- function(arg1, arg2) {
>
>    }
> --8<---------------cut here---------------end--------------->8---
>
> While playing about you may want to get rid of the "raw" directive so
> that the results will automatically be replaced on repeated evaluations.
>
> Dan
>
>>
>>
>>
>>>
>>>>>  Any suggestions how to best proceed?
>>>>>>
>>>>>> Dream: I would like to have one org file which contains everything
>>>>>> (documentation, code, other relevant files) and if I export or
>>>>>> tangle the file, I have the package ready.
>>>>>>
>>>>> Well, that functionality is essentially present with code blocks
>>>>> and tangling, except the documentation part.
>>>>>
>>>>
>> Exactly - and that is the part I would like to have.
>>
>>
>>>
>>>> Hi Erik,
>>>>
>>>> Would you mind expanding on that -- what are we missing for the
>>>> documentation part?
>>>>
>>>>
>>> Dan, by "except for the documentation part", I meant generating
>>> .Rd files (the LaTeX-like syntax) automatically from some org-syntax
>>> that does *not* depend on code blocks.  I.e., it would be cool to
>>> specify syntax like I have above for documentation.  Using org-mode
>>> headlines for each section like Description, Usage, Arguments, etc.
>>>
>>> Just like exporting to LaTeX generates sections, some process would
>>> use these headlines to generate the .Rd sections.
>>>
>>> That way, you don't have to use the .Rd syntax yourself.  No big deal,
>>> just a convenience feature.  I don't know how you'd specify to org-mode
>>> that a particular subtree was to generate .Rd syntax, and I don't know
>>> if it would be on export or tangling.
>>>
>>> An alternative is simply just to use code blocks of type Rd within
>>> org-mode and then tangle to .Rd files.  That's what I currently do.
>>>
>>> Hope that explains it,
>>> Erik
>>>
>>>
>>>  Dan
>>>>
>>>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>

Charles C. Berry                            (858) 534-2098
                                             Dept of Family/Preventive Medicine
E mailto:cberry@tajo.ucsd.edu	            UC San Diego
http://famprevmed.ucsd.edu/faculty/cberry/  La Jolla, San Diego 92093-0901