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>
Subject: Re: [babel] Writing R-packages the org way?
Date: Thu, 7 Oct 2010 18:18:26 +0200	[thread overview]
Message-ID: <AANLkTi=amfwJcDS1QcJA_pOorE+QOmoynyob+21ry2bX@mail.gmail.com> (raw)
In-Reply-To: <87y6aam1sq.fsf@stats.ox.ac.uk>

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

On Thu, Oct 7, 2010 at 5:59 PM, Dan Davison <davison@stats.ox.ac.uk> wrote:

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

I would not say that an Rd export target would be the solution, as only
parts of the document have to exported to .Rd format, and others (the code)
has to be tangled --- well, I guess one could do it in a two step process:
first exporting to .Rd based on the headers, and then tangling the code
blocks (which were not exported) into the same structure.

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

Agreed.

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

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