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

From: Rainer M Krug <r.m.krug@gmail.com>
To: Dan Davison <davison@stats.ox.ac.uk>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>,
	"Charles C. Berry" <cberry@tajo.ucsd.edu>
Subject: Re: [babel] Writing R-packages the org way?
Date: Fri, 8 Oct 2010 17:35:20 +0200	[thread overview]
Message-ID: <AANLkTimCgZWvSgFhEBg07E3umoFq7b5JnXFAf2pOd=au@mail.gmail.com> (raw)
In-Reply-To: <87fwwglwbi.fsf@stats.ox.ac.uk>

[-- Attachment #1.1: Type: text/plain, Size: 6716 bytes --]

On Fri, Oct 8, 2010 at 2:10 PM, Dan Davison <davison@stats.ox.ac.uk> wrote:

> Hi Chuck,
>
> I agree about making use of existing ESS tools and that a more
> traditional Org approach might be appropriate.
>

OK. But I think I have a solution for the "One package in a single org file"
approach - see below

>
> > 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.
>
> No extra code is needed to get editing support for languages.

> #+begin_src XXX
>
> provides an edit buffer in XXX-mode automatically, with no special
> customization. Also fontification in the org buffer works automatically
> if `org-src-fontify-natively' is set.
>

Agreed - and that is the key to it.

If one is using the post-tangle-hook to compile / check the package, the
fuinctiona;ity is together:

Example, the name of the org file will be used as the packagename:
------------BEGIN-----------------------

* Internal configurations
 :noexport:
** Post tangle script
#+begin_src sh :tangle postTangleScript.sh :var PACKAGENAME=(or
(buffer-file-name) org-current-export-file)
  R CMD CHECK $PACKAGENAME
#+end_src

** Evaluate to run post tangle script
#+begin_src emacs-lisp :results silent :tangle no :exports none
  (add-hook 'org-babel-post-tangle-hook
            (
             lambda ()
                    (call-process-shell-command "./postTangleScript.sh" nil
0 nil)
                    )
            )
#+end_src

* Package description
#+begin_src :tangle ./PACKAGENAME/DESCRIPTION
#+end_src
* Content of the package
** Function1
*** man
#+begin_src Rd :tangle ./PACKAGENAME/man/Function1.Rd
#+end_src

*** Code
#+begin_src R :tangle ./PACKAGENAME/R/Function1.R
#+end_src

*** Tests
#+begin_src R :tangle ./PACKAGENAME/tests/Function1Tests.R
#+end_src

The output from the test needs to be saved in
./PACKAGENAME/tests/Function1Tests.R - I still have to think about that.

** Function2
*** man
#+begin_src Rd :tangle ./PACKAGENAME/man/Function2.Rd
#+end_src

*** Code
#+begin_src R :tangle ./PACKAGENAME/R/Function2.R
#+end_src

*** Tests
#+begin_src R :tangle ./PACKAGENAME/tests/Function2Tests.R
#+end_src

The output from the test needs to be saved in
./PACKAGENAME/tests/Function2Tests.R - I still have to think about that.

** data
#+begin_src ...
#+end_src

This depends on the type of the data.

------------END-----------------------

This is untested so far, but I will try it out. The only thing which would
be nice, would be to automate a few things.

Cheers,

Rainer

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

-- 
NEW GERMAN FAX NUMBER!!!

Rainer M. Krug, PhD (Conservation Ecology, SUN), MSc (Conservation Biology,
UCT), Dipl. Phys. (Germany)

Centre of Excellence for Invasion Biology
Natural Sciences Building
Office Suite 2039
Stellenbosch University
Main Campus, Merriman Avenue
Stellenbosch
South Africa

Cell:           +27 - (0)83 9479 042
Fax:            +27 - (0)86 516 2782
Fax:            +49 - (0)321 2125 2244
email:          Rainer@krugs.de

Skype:          RMkrug
Google:         R.M.Krug@gmail.com

[-- Attachment #1.2: Type: text/html, Size: 14792 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
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