From mboxrd@z Thu Jan 1 00:00:00 1970 From: Dan Davison Subject: Re: [babel] Writing R-packages the org way? Date: Thu, 07 Oct 2010 18:16:43 +0100 Message-ID: <87pqvlncsk.fsf@stats.ox.ac.uk> References: <4CADD83B.4000602@ccbr.umn.edu> <8762xeniy6.fsf@stats.ox.ac.uk> <4CADE357.1090803@ccbr.umn.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from [140.186.70.92] (port=33796 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1P3uJs-0005Bf-I2 for emacs-orgmode@gnu.org; Thu, 07 Oct 2010 13:31:59 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1P3u5x-0000Kz-EO for emacs-orgmode@gnu.org; Thu, 07 Oct 2010 13:17:30 -0400 Received: from markov.stats.ox.ac.uk ([163.1.210.1]:58841) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1P3u5x-0000Kc-5h for emacs-orgmode@gnu.org; Thu, 07 Oct 2010 13:17:29 -0400 In-Reply-To: (Rainer M. Krug's message of "Thu, 7 Oct 2010 18:04:25 +0200") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Rainer M Krug Cc: emacs-orgmode Rainer M Krug writes: > On Thu, Oct 7, 2010 at 5:12 PM, Erik Iverson wrote: >> Dan Davison wrote: >>> Erik Iverson 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 >>> >>