From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Charles C. Berry" Subject: Re: Re: [babel] Writing R-packages the org way? Date: Thu, 7 Oct 2010 21:29:59 -0700 Message-ID: References: <4CADD83B.4000602@ccbr.umn.edu> <8762xeniy6.fsf@stats.ox.ac.uk> <4CADE357.1090803@ccbr.umn.edu> <87pqvlncsk.fsf@stats.ox.ac.uk> Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Return-path: Received: from [140.186.70.92] (port=50535 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1P44bC-0008Hc-GY for emacs-orgmode@gnu.org; Fri, 08 Oct 2010 00:30:27 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1P44bB-0006Zs-2e for emacs-orgmode@gnu.org; Fri, 08 Oct 2010 00:30:26 -0400 Received: from tajo.ucsd.edu ([137.110.122.165]:59618) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1P44bA-0006XG-My for emacs-orgmode@gnu.org; Fri, 08 Oct 2010 00:30:25 -0400 In-Reply-To: <87pqvlncsk.fsf@stats.ox.ac.uk> 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: Dan Davison Cc: emacs-orgmode , Rainer M Krug On Thu, 7 Oct 2010, Dan Davison wrote: > 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--- > 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