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

[Dan Davison]

Rainer M Krug <address@hidden> writes:

> On Thu, Oct 7, 2010 at 5:12 PM, Erik Iverson <address@hidden> wrote:
>> Dan Davison wrote:
>>> Erik Iverson <address@hidden> 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---

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