This project is basically about putting source code into org -files. This isn't just code to look pretty as a source code example, -but code to be evaluated. Org files have 3 main export targets: org, -html and latex. Thus the aim of this project is to produce files in -those formats that have benefitted in some way from the evaluation of -source code that is present in the source org file. We have a current -focus on R code, but we are regarding that more as a working example -than as a defining feature of the project. -
--Code evaluation can have three relevant consequences. Our aim is to -deal with these consequences as follows: -
- -We (optionally) incorporate the text output as text in the target -document -
We either link to the graphics or (html/latex) include them inline. -
? We link to other file output -
We bear this in mind -
-These objectives raise three questions: -
-Using some version of the code block ideas that Eric and Austin -have worked on. (In addition, an aim of org-R was to allow Org -users who are not R users to specify R code implicitly, using -native org syntax. I'd like to maintain that, but it's not central -to this project.) -
-Let's use an asterisk to indicate content which includes the -result of code evaluation, rather than the code itself. Clearly -we have a requirement for the following transformation: -
--org → org* -
--Let's say this transformation is effected by a function -`org-eval-buffer'. This transformation is necessary when the -target format is org (say you want to update the values in an org -table, or generate a plot and create an org link to it), and it -can also be used as the first step by which to reach html and -latex: -
--org → org* → html -
--org → org* → latex -
--Thus in principle we can reach our 3 target formats with -`org-eval-buffer', `org-export-as-latex' and `org-export-as-html'. -
--An extra transformation that we might want is -
--org → latex -
-
-I.e. export to latex without evaluation of code, in such a way that R
-code can subsequently be evaluated using
-Sweave(driver=RweaveLatex), which is what the R community is
-used to. This would provide a `bail out' avenue where users can
-escape org mode and enter a workflow in which the latex/noweb file
-is treated as source.
-
-AIUI The following can all be viewed as implementations of -org-eval-buffer for R code: -
-
-Sweave("file-with-unevaluated-code.org", driver=RweaveOrg, syntax=SweaveSyntaxOrg)
-
-
-Here we have to consider text/numeric output, and graphical -output. And also the stage at which evaluation occurs -
I think we're getting close to a comprehensive set of objectives -(although since you two are the real R user's I leave that decision up -to you). Once we've agreed on a set of objectives and agreed on at -least to broad strokes of implementation, I think we should start -listing out and assigning tasks. -
- -Org-mode includes orgtbl-mode, an extremely convenient way of using -tabular data in a plain text file. Currently, spreadsheet -functionality is available in org tables using the emacs package -calc. It would be a boon both to org users and R users to allow -org tables to be manipulated with the R programming language. Org -tables give R users an easy way to enter and display data; R gives -org users a powerful way to perform vector operations, statistical -tests, and visualization on their tables. -
- -(org-export-table "tmp.csv")
-and (ess-execute "read.csv('tmp.csv')").
-When R code evaluation generates vectors and 2-dimensional arrays, -this should be formatted appropriately in org buffers (orgtbl-mode) as well -as in export targets (html, latex) -
--Agreed, if we can convert the vector data to lists then we can use -the many orgtbl-to-* functions to convert the list to whatever -output format we desire. See `orgtbl-to-orgtbl, `orgtbl-to-latex', -`orgtbl-to-html', `orgtbl-to-csv', etc… -
-R can generate graphical output on a screen graphics device -(e.g. X11, quartz), and in various standard image file formats -(png, jpg, ps, pdf, etc). When graphical output is generated by -evaluation of R code in Org, at least the following two things are desirable: -
At first I was leaning towards leaving the exporting to Sweave, but it -seems that once we have evaluation or R working, it will not be -difficult to implement full evaluation of R blocks, one-liners, and -creation of R graphics on export directly in elisp. -
--I think that this would be worth the effort since it would eliminate -the need for using Sweave, and would allow for exportation to any -target format supported by org-mode. -
- -Unfortunately org-mode how two different block types, both useful. -In developing RweaveOrg, a third was introduced. -
-
-Eric is leaning towards using the #+begin_src blocks, as that is
-really what these blocks contain: source code. Austin believes
-that specifying export options at the beginning of a block is
-useful functionality, to be preserved if possible.
-
-Note that upper and lower case are not relevant in block headings. -
- -I (Eric) propose that we use the syntax of source code blocks as they -currently exist in org-mode with the addition of evaluation, -header-arguments, exportation, single-line-blocks, and -references-to-table-data. -
-\C-c\C-c with
-a slight addition to the code already present and working in
-org-eval-light.el. All we should need to add for R support would
-be an appropriate entry in org-eval-light-interpreters with a
-corresponding evaluation function. For an example usinga
-org-eval-light see * src block evaluation w/org-eval-light.
-
-#+R: lines? I would lean
-towards something here that can be re-used for any type of source
-code in the same manner as the #+begin_src R blocks, maybe
-#+src_R?
-
-What do you think? Does this accomplish everything we want to be able -to do with embedded R source code blocks? -
--first load the org-eval-light.el file -
--<elisp:(load (expand-file-name "org-eval-light.el" (expand-file-name "existing_tools" (file-name-directory buffer-file-name))))> -
-
-then press \C-c\C-c inside of the following src code snippet. The
-results should appear in a comment immediately following the source
-code block. It shouldn't be too hard to add R support to this
-function through the `org-eval-light-interpreters' variable.
-
-(Dan: The following causes error on export to HTML hence spaces inserted at bol) -
--#+beginsrc shell -date -#+endsrc -
-Org has an extremely useful method of editing source code and -examples in their native modes. In the case of R code, we want to -be able to use the full functionality of ESS mode, including -interactive evaluation of code. -
--Source code blocks look like the following and allow for the -special editing of code inside of the block through -`org-edit-special'. -
- - - -- -,## hit C-c ' within this block to enter a temporary buffer in r-mode. - -,## while in the temporary buffer, hit C-c C-c on this comment to -,## evaluate this block -a <- 3 -a - -,## hit C-c ' to exit the temporary buffer -- - - - -
dblocks are useful because org-mode will automatically call
-`org-dblock-write:dblock-type' where dblock-type is the string
-following the #+BEGIN: portion of the line.
-
-dblocks look like the following and allow for evaluation of the
-code inside of the block by calling \C-c\C-c on the header of
-the block.
-
In developing RweaveOrg, Austin created org-sweave.el. This -allows for the kind of blocks shown in testing.Rorg. These blocks -have the advantage of accepting options to the Sweave preprocessor -following the #+BEGINR declaration. -
--We should take care to implement this in such a way that all of the -different components which have to interactive with R including: -
I think we currently have two implementations of interaction with R -processes; org-R.el and org-exp-blocks.el. We should be sure to take -the best of each of these approaches. -
- -LocalWords: DBlocks dblocks -
Date: 2009-02-08 14:56:13 EST
-HTML generated by org-mode 6.21trans in emacs 22
-