From: Dan Davison <davison@stats.ox.ac.uk>
To: Rainer M Krug <r.m.krug@gmail.com>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: [babel] Writing R-packages the org way?
Date: Thu, 07 Oct 2010 18:16:43 +0100 [thread overview]
Message-ID: <87pqvlncsk.fsf@stats.ox.ac.uk> (raw)
In-Reply-To: <AANLkTimW4hmahYhfGJYT6bOM+zYb_sR88b1a6qQT4kSN@mail.gmail.com> (Rainer M. Krug's message of "Thu, 7 Oct 2010 18:04:25 +0200")
Rainer M Krug <r.m.krug@gmail.com> writes:
> On Thu, Oct 7, 2010 at 5:12 PM, Erik Iverson <eriki@ccbr.umn.edu> wrote:
>> 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) {
>>>>
>>>> }
>>>>
>>>>
> 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
>>>
>>
next prev parent reply other threads:[~2010-10-07 17:31 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-10-07 14:02 [babel] Writing R-packages the org way? Rainer M Krug
2010-10-07 14:24 ` Erik Iverson
2010-10-07 15:03 ` Dan Davison
2010-10-07 15:12 ` Erik Iverson
2010-10-07 15:59 ` Dan Davison
2010-10-07 16:18 ` Rainer M Krug
2010-10-07 16:04 ` Rainer M Krug
2010-10-07 17:16 ` Dan Davison [this message]
2010-10-08 4:29 ` Charles C. Berry
2010-10-08 12:10 ` Dan Davison
2010-10-08 13:09 ` Stephen Eglen
2010-10-08 15:41 ` Rainer M Krug
2010-10-08 15:35 ` Rainer M Krug
2010-10-07 14:25 ` Dan Davison
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87pqvlncsk.fsf@stats.ox.ac.uk \
--to=davison@stats.ox.ac.uk \
--cc=emacs-orgmode@gnu.org \
--cc=r.m.krug@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).