emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Charles C. Berry
Subject: Re: [Orgmode] Re: [babel] Writing R-packages the org way?
Date: Thu, 7 Oct 2010 21:29:59 -0700

On Thu, 7 Oct 2010, Dan Davison wrote:

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


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.
address@hidden
http://lists.gnu.org/mailman/listinfo/emacs-orgmode


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





reply via email to

[Prev in Thread] Current Thread [Next in Thread]