* [babel] Writing R-packages the org way? @ 2010-10-07 14:02 Rainer M Krug 2010-10-07 14:24 ` Erik Iverson 2010-10-07 14:25 ` Dan Davison 0 siblings, 2 replies; 14+ messages in thread From: Rainer M Krug @ 2010-10-07 14:02 UTC (permalink / raw) To: emacs-orgmode [-- Attachment #1.1: Type: text/plain, Size: 1052 bytes --] 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? 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. Is there anything like that? Rainer -- 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: 1369 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 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 14:25 ` Dan Davison 1 sibling, 1 reply; 14+ messages in thread From: Erik Iverson @ 2010-10-07 14:24 UTC (permalink / raw) To: Rainer M Krug; +Cc: emacs-orgmode 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. > > Is there anything like that? > > Rainer > > -- > 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 <mailto:Rainer@krugs.de> > > Skype: RMkrug > Google: R.M.Krug@gmail.com <mailto:R.M.Krug@gmail.com> > > > ------------------------------------------------------------------------ > > _______________________________________________ > 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 2010-10-07 14:24 ` Erik Iverson @ 2010-10-07 15:03 ` Dan Davison 2010-10-07 15:12 ` Erik Iverson 0 siblings, 1 reply; 14+ messages in thread From: Dan Davison @ 2010-10-07 15:03 UTC (permalink / raw) To: Erik Iverson; +Cc: emacs-orgmode, Rainer M Krug 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 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:04 ` Rainer M Krug 0 siblings, 2 replies; 14+ messages in thread From: Erik Iverson @ 2010-10-07 15:12 UTC (permalink / raw) To: Dan Davison; +Cc: emacs-orgmode, Rainer M Krug 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, Erik > Dan ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 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 1 sibling, 1 reply; 14+ messages in thread From: Dan Davison @ 2010-10-07 15:59 UTC (permalink / raw) To: Erik Iverson; +Cc: emacs-orgmode, Rainer M Krug 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. Well, anyone who wants to put Bastien's new export machinery to the test, I'll have a texinfo and an Rd backend please. :) 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 2010-10-07 15:59 ` Dan Davison @ 2010-10-07 16:18 ` Rainer M Krug 0 siblings, 0 replies; 14+ messages in thread From: Rainer M Krug @ 2010-10-07 16:18 UTC (permalink / raw) To: Dan Davison; +Cc: emacs-orgmode [-- 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 2010-10-07 15:12 ` Erik Iverson 2010-10-07 15:59 ` Dan Davison @ 2010-10-07 16:04 ` Rainer M Krug 2010-10-07 17:16 ` Dan Davison 1 sibling, 1 reply; 14+ messages in thread From: Rainer M Krug @ 2010-10-07 16:04 UTC (permalink / raw) To: Erik Iverson; +Cc: Dan Davison, emacs-orgmode [-- Attachment #1.1: Type: text/plain, Size: 3405 bytes --] 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)? > >>> 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 >> > -- 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: 5531 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 2010-10-07 16:04 ` Rainer M Krug @ 2010-10-07 17:16 ` Dan Davison 2010-10-08 4:29 ` Charles C. Berry 0 siblings, 1 reply; 14+ messages in thread From: Dan Davison @ 2010-10-07 17:16 UTC (permalink / raw) To: Rainer M Krug; +Cc: emacs-orgmode 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 >>> >> ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: Re: [babel] Writing R-packages the org way? 2010-10-07 17:16 ` Dan Davison @ 2010-10-08 4:29 ` Charles C. Berry 2010-10-08 12:10 ` Dan Davison 0 siblings, 1 reply; 14+ messages in thread From: Charles C. Berry @ 2010-10-08 4:29 UTC (permalink / raw) To: Dan Davison; +Cc: emacs-orgmode, Rainer M Krug On Thu, 7 Oct 2010, Dan Davison wrote: > 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--- > 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 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:35 ` Rainer M Krug 0 siblings, 2 replies; 14+ messages in thread From: Dan Davison @ 2010-10-08 12:10 UTC (permalink / raw) To: Charles C. Berry; +Cc: emacs-orgmode, Rainer M Krug Hi Chuck, I agree about making use of existing ESS tools and that a more traditional Org approach might be appropriate. > 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. 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 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 1 sibling, 1 reply; 14+ messages in thread From: Stephen Eglen @ 2010-10-08 13:09 UTC (permalink / raw) To: emacs-orgmode; +Cc: S.J.Eglen Dan Davison <davison@stats.ox.ac.uk> writes: > Hi Chuck, > > I agree about making use of existing ESS tools and that a more > traditional Org approach might be appropriate. this may be slightly off-topic, but another way of adding documentation is to the 'roxygen' markup. http://roxygen.org/ ESS has some support for editing roxygen comment chunks within ESS buffers, Stephen ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: Re: [babel] Writing R-packages the org way? 2010-10-08 13:09 ` Stephen Eglen @ 2010-10-08 15:41 ` Rainer M Krug 0 siblings, 0 replies; 14+ messages in thread From: Rainer M Krug @ 2010-10-08 15:41 UTC (permalink / raw) To: Stephen Eglen; +Cc: emacs-orgmode [-- Attachment #1.1: Type: text/plain, Size: 1632 bytes --] On Fri, Oct 8, 2010 at 3:09 PM, Stephen Eglen <S.J.Eglen@damtp.cam.ac.uk>wrote: > > > > Dan Davison <davison@stats.ox.ac.uk> writes: > > > Hi Chuck, > > > > I agree about making use of existing ESS tools and that a more > > traditional Org approach might be appropriate. > > this may be slightly off-topic, but another way of adding documentation > is to the 'roxygen' markup. > http://roxygen.org/ Actually not - I did not specify that I want to use .Rd . > > ESS has some support for editing roxygen comment chunks within ESS > buffers, > Yes - I looked into Roxygen some time ago, but in the context of org, I see it as not necessary to include the documentation in the source code block - when using #+begin_src Rd #+end_src and #+begin_src R #+end_src I can nicely separate these two on the code level - but in the org file, they are still literate programming. Cheers, Rainer > Stephen > > > _______________________________________________ > 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: 3124 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 2010-10-08 12:10 ` Dan Davison 2010-10-08 13:09 ` Stephen Eglen @ 2010-10-08 15:35 ` Rainer M Krug 1 sibling, 0 replies; 14+ messages in thread From: Rainer M Krug @ 2010-10-08 15:35 UTC (permalink / raw) To: Dan Davison; +Cc: emacs-orgmode, Charles C. Berry [-- 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 ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [babel] Writing R-packages the org way? 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 14:25 ` Dan Davison 1 sibling, 0 replies; 14+ messages in thread From: Dan Davison @ 2010-10-07 14:25 UTC (permalink / raw) To: Rainer M Krug; +Cc: emacs-orgmode Rainer M Krug <r.m.krug@gmail.com> writes: > 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? > > 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. > > Is there anything like that? Hi Rainer, This sounds like a seriously good idea, and I wish it already existed. However...not as far as I know. I'd be very happy to help in any way I can if you decide to take this on. Dan > > Rainer ^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2010-10-08 15:42 UTC | newest] Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 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 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
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).