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

From: Dan Davison <davison@stats.ox.ac.uk>
To: Erik Iverson <eriki@ccbr.umn.edu>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>,
	Rainer M Krug <r.m.krug@gmail.com>
Subject: Re: [babel] Writing R-packages the org way?
Date: Thu, 07 Oct 2010 16:59:33 +0100	[thread overview]
Message-ID: <87y6aam1sq.fsf@stats.ox.ac.uk> (raw)
In-Reply-To: <4CADE357.1090803@ccbr.umn.edu> (Erik Iverson's message of "Thu, 07 Oct 2010 10:12:23 -0500")

Erik Iverson <eriki@ccbr.umn.edu> writes:

> 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) {
>>>
>>>     }
>>>
>>>
>>>> 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.
>>
>> 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,

Yes perfectly, thanks. I had only thought of the solution you mention
involving writing Rd explicitly; I hadn't thought of Rd as an export
target.

Well, anyone who wants to put Bastien's new export machinery to the
test, I'll have a texinfo and an Rd backend please.

:)

Dan

> 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