moving images to doc/images
[org-mode.git] / org-babel-requirements.org
blob6d19e3a3e24707509ce9bce813e2472a047ef4a4
1 #+TITLE: Org-Babel Requirements
2 #+OPTIONS: toc:nil num:nil ^:nil
4 This file contains the initial discussion of the requirements for
5 org-babel.
7 * Overview
8 This project is basically about putting source code into org
9 files. This isn't just code to look pretty as a source code example,
10 but code to be evaluated. Org files have 3 main export targets: org,
11 html and latex. Once we have implemented a smooth bi-directional flow
12 of data between org-mode formats (including tables, and maybe lists
13 and property values) and source-code blocks, we will be able to use
14 org-mode's built in export to publish the results of evaluated source
15 code in any org-supported format using org-mode as an intermediate
16 format.  We have a current focus on R code, but we are regarding that
17 more as a working example than as a defining feature of the project.
19 The main objectives of this project are...
21 # Lets start with this list and make changes as appropriate.  Please
22 # try to make changes to this list, rather than starting any new
23 # lists.
25 - [[* evaluation of embedded source code][evaluation of embedded source code]]
26   - [[* execution on demand and on export][execution on demand and on export]]
27   - [[* source blocks][source blocks]]
28   - [[* header arguments][header arguments]]
29   - [[* inline source evaluation][inline source evaluation]]
30   - [[* included source file evaluation][included source file evaluation]] ?? maybe
31   - [[* caching of evaluation][caching of evaluation]]
32 - [[* interaction with the source-code's process][interaction with the source-code's process]]
33 - [[* output of code evaluation][output of code evaluation]]
34   - [[* textual/numeric output][textual/numeric output]]
35   - [[* graphical output][graphical output]]
36   - [[* file creation][non-graphics file creation]]
37   - [[* side effects][side effects]]
38 - [[* reference to data and evaluation results][reference to data and evaluation results]]
39   - [[* reference format][reference format]]
40   - [[* source-target pairs][source-target pairs]]
41     - [[* source block output from org tables][source block output from org tables]]
42     - [[* source block outpt from other source block][source block outpt from other source block]]
43     - [[* source block output from org list][source block output from org list]] ?? maybe
44     - [[* org table from source block][org table from source block]]
45     - [[* org table from org table][org table from org table]]
46     - [[* org properties from source block][org properties from source block]]
47     - [[* org properties from org table][org properties from org table]]
48 - [[* export][export]]
51 * Objectives and Specs
53 ** evaluation of embedded source code
55 *** execution on demand and on export
56     Let's use an asterisk to indicate content which includes the
57     *result* of code evaluation, rather than the code itself. Clearly
58     we have a requirement for the following transformation:
60     org \to org*
62     Let's say this transformation is effected by a function
63     `org-eval-buffer'. This transformation is necessary when the
64     target format is org (say you want to update the values in an org
65     table, or generate a plot and create an org link to it), and it
66     can also be used as the first step by which to reach html and
67     latex:
68     
69     org \to org* \to html
71     org \to org* \to latex
73     Thus in principle we can reach our 3 target formats with
74     `org-eval-buffer', `org-export-as-latex' and `org-export-as-html'.
75     
76     An extra transformation that we might want is
77     
78     org \to latex
80     I.e. export to latex without evaluation of code, in such a way that R
81     code can subsequently be evaluated using
82     =Sweave(driver=RweaveLatex)=, which is what the R community is
83     used to. This would provide a `bail out' avenue where users can
84     escape org mode and enter a workflow in which the latex/noweb file
85     is treated as source.
87 **** How do we implement `org-eval-buffer'?
88     
89      AIUI The following can all be viewed as implementations of
90      org-eval-buffer for R code:
92      (see this question again posed in [[file:org-babel/org-babel-R.el::Maybe%20the%20following%20be%20replaced%20with%20a%20method%20using%20ess%20execute][org-babel-R.el]])
93     
94 ***** org-eval-light
95       This is the beginnings of a general evaluation mechanism, that
96       could evaluate python, ruby, shell, perl, in addition to R.
97       The header says it's based on org-eval
99       what is org-eval??
100       
101       org-eval was written by Carsten.  It lives in the
102       org/contrib/lisp directory because it is too dangerous to
103       include in the base.  Unlike org-eval-light org-eval evaluates
104       all source blocks in an org-file when the file is first opened,
105       which could be a security nightmare for example if someone
106       emailed you a pernicious file.
107       
108 ***** org-R
109       This accomplishes org \to org* in elisp by visiting code blocks
110       and evaluating code using ESS.
112 ***** RweaveOrg
113       This accomplishes org \to org* using R via
114       
115 : Sweave("file-with-unevaluated-code.org", driver=RweaveOrg, syntax=SweaveSyntaxOrg)
117 ***** org-exp-blocks.el
118       Like org-R, this achieves org \to org* in elisp by visiting code
119       blocks and using ESS to evaluate R code.
121 *** source blocks
122 (see [[* Special editing and evaluation of source code][Special editing and evaluation of source code]])
124 *** header arguments
125 (see [[* block headers/parameters][block headers/parameters]])
127 There are going to be many cases where we want to use header arguments
128 to change the evaluation options of source code, to pass external
129 information to a block of source code and control the inclusion of
130 evaluation results.
132 *** inline source evaluation
133 *** included source file evaluation
134 It may be nice to be able to include an entire external file of source
135 code, and then evaluate and export that code as if it were in the
136 file.  The format for such a file inclusion could optionally look like
137 the following
139 : #+include_src filename header_arguments
141 *** caching of evaluation
143 Any kind of code that can have a block evaluated could optionally define
144 a function to write the output to a file, or to serialize the output of
145 the function.  If a document or block is configured to cache input,
146 write all cached blocks to their own files and either a) hash them, or
147 b) let git and org-attach track them.  Before a block gets eval'd, we
148 check to see if it has changed.  If a document or block is configured to
149 cache output and a print/serialize function is available, write the
150 output of each cached block to its own file.  When the file is eval'd
151 and some sort of display is called for, only update the display if the
152 output has changed.  Each of these would have an override, presumably
153 something like (... & force) that could be triggered with a prefix arg
154 to the eval or export function.
156 For R, I would say
158 #+begin_src emacs-lisp
159 ;; fake code that only pretends to work
160 (add-hook 'rorg-store-output-hook 
161     '("r" lambda (block-environment block-label)
162         (ess-exec (concat "save.image("
163                           block-environment
164                           ", file = " block-label
165                           ".Rdata, compress=TRUE)"))))
166 #+end_src
168 The idea being that for r blocks that get eval'd, if output needs to be
169 stored, you should write the entire environment that was created in that
170 block to an Rdata file.
172 (see [[* block scoping][block scoping]])
174 ** interaction with the source-code's process
175 We should settle on a uniform API for sending code and receiving
176 output from a source process.  Then to add a new language all we need
177 to do is implement this API.
179 for related notes see ([[* Interaction with the R process][Interaction with the R process]])
181 ** output of code evaluation
182 *** textual/numeric output
183     We (optionally) incorporate the text output as text in the target
184     document
185 *** graphical output
186     We either link to the graphics or (html/latex) include them
187     inline.
188     
189     I would say, if the block is being evaluated interactively then
190     lets pop up the image in a new window, and if it is being exported
191     then we can just include a link to the file which will be exported
192     appropriately by org-mode.
193     
194 *** non-graphics files
195     ? We link to other file output
196 *** side effects
197 If we are using a continuous process in (for example an R process
198 handled by ESS) then any side effects of the process (for example
199 setting values of R variables) will be handled automatically
201 Are there side-effects which need to be considered aside from those
202 internal to the source-code evaluation process?
204 ** reference to data and evaluation results
205    I think this will be very important.  I would suggest that since we
206    are using lisp we use lists as our medium of exchange.  Then all we
207    need are functions going converting all of our target formats to and
208    from lists.  These functions are already provided by for org tables.
210    It would be a boon both to org users and R users to allow org tables
211    to be manipulated with the R programming language.  Org tables give R
212    users an easy way to enter and display data; R gives org users a
213    powerful way to perform vector operations, statistical tests, and
214    visualization on their tables.
216    This means that we will need to consider unique id's for source
217    blocks, as well as for org tables, and for any other data source or
218    target.
220 *** Implementations
221 **** naive
222      Naive implementation would be to use =(org-export-table "tmp.csv")=
223      and =(ess-execute "read.csv('tmp.csv')")=.  
224 **** org-R
225      org-R passes data to R from two sources: org tables, or csv
226      files. Org tables are first exported to a temporary csv file
227      using [[file:existing_tools/org-R.el::defun%20org%20R%20export%20to%20csv%20csv%20file%20options][org-R-export-to-csv]].
228 **** org-exp-blocks
229      org-exp-blocks uses [[org-interblock-R-command-to-string]] to send
230      commands to an R process running in a comint buffer through ESS.
231      org-exp-blocks has no support for dumping table data to R process, or
232      vice versa.
234 **** RweaveOrg
235      NA
237 *** reference format
238     This will be tricky, Dan has already come up with a solution for R, I
239     need to look more closely at that and we should try to come up with a
240     formats for referencing data from source-code in such a way that it
241     will be as source-code-language independent as possible.
242     
243     Org tables already have a sophisticated reference system in place
244     that allows referencing table ranges in other files, as well as
245     specifying constants in the header arguments of a table.  This is
246     described in [[info:org:References]].
248 **** Dan: thinking aloud re: referencing data from R
249      Suppose in some R code, we want to reference data in an org
250      table. I think that requires the use of 'header arguments', since
251      otherwise, under pure evaluation of a code block without header
252      args, R has no way to locate the data in the org buffer. So that
253      suggests a mechanism like that used by org-R whereby table names
254      or unique entry IDs are used to reference org tables (and indeed
255      potentially row/column ranges within org tables, although that
256      subsetting could also be done in R).
258      Specifically what org-R does is write the table to a temp csv
259      file, and tell R the name of that file. However:
261      1. We are not limited to a single source of input; the same sort
262         of thing could be done for several sources of input
264      2. I don't think we even have to use temp files. An alternative
265         would be to have org pass the table contents as a csv-format
266         string to textConnection() in R, thus creating an arbitrary
267         number of input objects in the appropriate R environment
268         (scope) from which the R code can read data when necessary.
270         That suggests a header option syntax something like
271     
272 #+begin_src emacs-lisp
273 '(:R-obj-name-1 tbl-name-or-id-1 :R-obj-name-2 tbl-name-or-id-2)
274 #+end_src
276 As a result of passing that option, the code would be able to access
277 the data referenced by table-name-or-id-2 via read.table(R-obj-name-1).
279 An extension of that idea would be to allow remote files to be used as
280 data sources. In this case one might need just the remote file (if
281 it's a csv file), or if it's an org file then the name of the file
282 plus a table reference within that org file. Thus maybe something like
284 #+begin_src emacs-lisp
285 '((R-obj-name-1 . (:tblref tbl-name-or-id-1 :file file-1))
286   (R-obj-name-2 . (:tblref tbl-name-or-id-2 :file file-2)))
287 #+end_src emacs-lisp
289 **** Eric: referencing data in general
290 So here's some thoughts for referencing data (henceforth referred to
291 as *resources*).  I think this is the next thing we need to tackle for
292 implementation to move forward.  We don't need to implement everything
293 below right off the bat, but I'd like to get these lists as full as
294 possible so we don't make any implementation assumptions which
295 preclude real needs.
297 We need to reference resources of the following types...
299 - table (list)
300 - output from a source code block (list or hash)
301 - property values of an outline header (hash)
302 - list (list)
303 - description list (hash)
304 - more?...
306 All of these resources will live in org files which could be
308 - the current file (default)
309 - another file on the same system (path)
310 - another file on the web (url)
311 - another file in a git repo (file and commit hash)
313 What information should each of these resources be able to supply?
314 I'm thinking (again not that we'll implement all of these but just to
315 think of them)...
317 - ranges or points of vector data
318 - key/value pairs from a hash
319 - when the object was last modified
320 - commit info (author, date, message, sha, etc...)
321 - pointers to the resources upon which the resource relies
323 So we need a referencing syntax powerful enough to handle all of these
324 alternatives.  Maybe something like =path:sha:name:range= where
326 - path :: is empty for the current file, is a path for files on the
327           same system, and is a url otherwise
328 - sha :: is an option git commit indicator
329 - name :: is the table/header/source-block name or id for location
330           inside of the org file (this would not be optional)
331 - range :: would indicate which information is requested from the
332            resource, so it could be a range to access parts of a
333            table, or the names of properties to be referenced from an
334            outline header
336 Once we agree on how this should work, I'll try to stub out some code,
337 so that we can get some simple subset of this functionality working,
338 hopefully something complex enough to do the following...
339 - [[* resource reference example][resource-reference-example]]
341 ***** questions
342 ****** multiple outputs
343 Do we want things like a source code block to leave multiple outputs,
344 or do we only want them to be able to output one vector or hash?
346 ****** environment (state and side-effects)
347 This design assumes that any changes will explicitly pass data in a
348 functional programming style.  This makes no assumptions about things
349 like source code blocks changing state (in general state changes lead
350 to more difficult debugging).
352 - Do we want to take steps so ensure we do things like execute
353   consecutive R blocks in different environment, or do we want to
354   allow state changes?
355 - Does this matter?
357 ****** passing arguments to resources
358 So I(eric) may be getting ahead of myself here, but what do you think
359 about the ability to pass arguments to resources.  I'm having visions
360 of google map-reduce, processes spread out across multiple machines.
362 Maybe we could do this by allowing the arguments to be specified?
364 *** source-target pairs
366     The following can be used for special considerations based on
367     source-target pairs
369     Dan: I don't quite understand this subtree; Eric -- could you give
370     a little more explanation of this and of your comment above
371     regarding using [[lists as our medium of exchange]]?
372     
373 **** source block output from org tables
374 **** source block outpt from other source block
375 **** source block output from org list
376 **** org table from source block
377 **** org table from org table
378 **** org properties from source block
379 **** org properties from org table
380      
381 ** export
382    once the previous objectives are met export should be fairly simple.
383    Basically it will consist of triggering the evaluation of source code
384    blocks with the org-export-preprocess-hook.
386    This block export evaluation will be aware of the target format
387    through the htmlp and latexp variables, and can then create quoted
388    =#+begin_html= and =#+begin_latex= blocks appropriately.
389    
390    There will also need to be a set of header arguments related to
391    code export.  These would be similar to the results header
392    arguments but would apply to how to handle execution and results
393    during export.
396 * Notes
397 ** Block Formats
398    Unfortunately org-mode how two different block types, both useful.
399    In developing RweaveOrg, a third was introduced.
401    Eric is leaning towards using the =#+begin_src= blocks, as that is
402    really what these blocks contain: source code.  Austin believes
403    that specifying export options at the beginning of a block is
404    useful functionality, to be preserved if possible.
406    Note that upper and lower case are not relevant in block headings.
408 *** PROPOSED block format
409 I (Eric) propose that we use the syntax of source code blocks as they
410 currently exist in org-mode with the addition of *evaluation*,
411 *header-arguments*, *exportation*, *single-line-blocks*, and
412 *references-to-table-data*.
414 1) *evaluation*: These blocks can be evaluated through =\C-c\C-c= with
415    a slight addition to the code already present and working in
416    [[file:existing_tools/org-eval-light.el][org-eval-light.el]].  All we should need to add for R support would
417    be an appropriate entry in [[org-eval-light-interpreters]] with a
418    corresponding evaluation function.  For an example usinga
419    org-eval-light see [[* src block evaluation w/org-eval-light]].
421 2) *header-arguments*: These can be implemented along the lines of
422    Austin's header arguments in [[file:existing_tools/RweaveOrg/org-sweave.el][org-sweave.el]].
424 3) *exportation*: Should be as similar as possible to that done by
425    Sweave, and hopefully can re-use some of the code currently present
426    in [[file:existing_tools/exp-blocks/org-exp-blocks.el ][org-exp-blocks.el]].
428 4) *single-line-blocks*: It seems that it is useful to be able to
429    place a single line of R code on a line by itself.  Should we add
430    syntax for this similar to Dan's =#+RR:= lines?  I would lean
431    towards something here that can be re-used for any type of source
432    code in the same manner as the =#+begin_src R= blocks, maybe
433    =#+src_R=? Dan: I'm fine with this, but don't think single-line
434    blocks are a priority. My =#+R= lines were something totally
435    different: an attempt to have users specify R code implicitly,
436    using org-mode option syntax.
438 5) *references-to-table-data*: I get this impression that this is
439    vital to the efficient use of R code in an org file, so we should
440    come up with a way to reference table data from a single-line-block
441    or from an R source-code block.  It looks like Dan has already done
442    this in [[file:existing_tools/org-R.el][org-R.el]].
444 Syntax
446 Multi-line Block
447 : #+begin_src lang header-arguments
448 :  body
449 : #+end
450 - lang :: the language of the block (R, shell, elisp, etc...)
451 - header-arguments :: a list of optional arguments which control how
452      the block is evaluated and exported, and how the results are handled
453 - body :: the actual body of the block
455 Single-line Block
456 : #+begin_src lang body
457 - It's not clear how/if we would include header-arguments into a
458   single line block.  Suggestions? Can we just leave them out?  Dan:
459   I'm not too worried about single line blocks to start off
460   with. Their main advantage seems to be that they save 2 lines.
461   Eric: Fair enough, lets not worry about this now, also I would guess
462   that any code simple enough to fit on one line wouldn't need header
463   arguments anyways.
465 Include Block
466 : #+include_src lang filename header-arguments
467 - I think this would be useful, and should be much more work (Dan:
468   didn't get the meaning of that last clause!?).  Eric: scratch that,
469   I meant "*shouldn't* be too much work" :) That way whole external
470   files of source code could be evaluated as if they were an inline
471   block. Dan: again I'd say not a massive priority, as I think all the
472   languages we have in mind have facilities for doing this natively,
473   thus I think the desired effect can often be achieved from within a
474   #+begin_src block.  Eric: Agreed, while this would be a nice thing
475   to include we shouldn't wast too much effort on it in the beginning.
477 What do you think?  Does this accomplish everything we want to be able
478 to do with embedded R source code blocks?
480 ***** src block evaluation w/org-eval-light
481 here's an example using org-eval-light.el
483 first load the org-eval-light.el file
485 [[elisp:(load (expand-file-name "org-eval-light.el" (expand-file-name "existing_tools" (file-name-directory buffer-file-name))))]]
487 then press =\C-c\C-c= inside of the following src code snippet.  The
488 results should appear in a comment immediately following the source
489 code block.  It shouldn't be too hard to add R support to this
490 function through the `org-eval-light-interpreters' variable.
492 (Dan: The following causes error on export to HTML hence spaces inserted at bol)
494  #+begin_src shell
495 date
496  #+end_src
498 *** existing formats
499 **** Source code blocks 
500     Org has an extremely useful method of editing source code and
501     examples in their native modes.  In the case of R code, we want to
502     be able to use the full functionality of ESS mode, including
503     interactive evaluation of code.
505     Source code blocks look like the following and allow for the
506     special editing of code inside of the block through
507     `org-edit-special'.
509 #+BEGIN_SRC r
511 ,## hit C-c ' within this block to enter a temporary buffer in r-mode.
513 ,## while in the temporary buffer, hit C-c C-c on this comment to
514 ,## evaluate this block
515 a <- 3
518 ,## hit C-c ' to exit the temporary buffer
519 #+END_SRC     
521 **** dblocks
522     dblocks are useful because org-mode will automatically call
523     `org-dblock-write:dblock-type' where dblock-type is the string
524     following the =#+BEGIN:= portion of the line.
526     dblocks look like the following and allow for evaluation of the
527     code inside of the block by calling =\C-c\C-c= on the header of
528     the block.  
530 #+BEGIN: dblock-type
531 #+END:
533 **** R blocks
534      In developing RweaveOrg, Austin created [[file:existing_tools/RweaveOrg/org-sweave.el][org-sweave.el]].  This
535      allows for the kind of blocks shown in [[file:existing_tools/RweaveOrg/testing.Rorg][testing.Rorg]].  These blocks
536      have the advantage of accepting options to the Sweave preprocessor
537      following the #+BEGIN_R declaration.
539 *** block headers/parameters
540 Regardless of the syntax/format chosen for the source blocks, we will
541 need to be able to pass a list of parameters to these blocks.  These
542 should include (but should certainly not be limited to)
543 - label or id :: Label of the block, should we provide facilities for
544                  automatically generating a unique one of these?
545 - file :: names of file to which graphical/textual/numerical/tabular output
546   should be written.  Do we need this, or should this be controlled
547   through the source code itself?
548 - results :: indication of where the results should be placed, maybe
549              the following values...
550   - append :: *default* meaning just append to the current buffer
551               immediately following the current source block
552   - replace :: like append, but replace any results currently there
553   - file :: save the results in a new file, and place a link to the
554             file into the current buffer immediately following the
555             source code block
556   - table :: save the results into a table, maybe use a table id:range
557              to identify which table and where therein
558   - nil :: meaning just discard the results
559 - not sure of a good name here :: flags for when/if the block should
560      be evaluated (on export etc...)
561 - again can't thing of a concise name :: flags for how the results of
562      the export should be displayed/included
563 - scope :: flag indicating whether the block should have a local or
564            global scope
565 - flags specific to the language of the source block
566 - etc...
568 I think fleshing out this list is an important next step.
570 ** Interaction with the R process
572 We should take care to implement this in such a way that all of the
573 different components which have to interactive with R including:
574 - evaluation of source code blocks
575 - automatic evaluation on export
576 - evaluation of \R{} snippets
577 - evaluation of single source code lines
578 - evaluation of included source code files
579 - sending/receiving vector data
581 I think we currently have two implementations of interaction with R
582 processes; [[file:existing_tools/org-R.el][org-R.el]] and [[file:existing_tools/exp-blocks/org-exp-blocks.el ][org-exp-blocks.el]].  We should be sure to take
583 the best of each of these approaches.
585 More on the exchange of data at between org-mode and source code
586 blocks at [[* reference to data and evaluation results][reference to data and evaluation results]].
588 ** block scoping
589 (see [[* caching of evaluation][caching of evaluation]])
591 This inadvertently raises the issue of scoping.  The pretend function
592 pretends that we will create a block-local scope, and that we can save
593 just the things in that scope.  Sweave takes the make-everything-global
594 approach.  I can see advantages either way.  If we make block-local
595 scopes, we can save each one independently, and generally speaking it
596 seems like more granularity==more control.  If we make everything
597 global, we can refer to entities declared in earlier blocks without
598 having to explicitly import those entities into the current block.  I
599 think this counts in the "need to think about it early on" category.
601 If we did want block-local scopes, in R we can start every eval with
602 something like
604 ;; fake code that pretends to create a new, empty environment
605 (ess-exec (concat block-env " <- new.env()"))
606 (ess-exec (concat "eval(" block-contents ", envir=" block-env ")"))
608 If we decide we want block-scoping, I'm sure Dan and I can figure out
609 the right way to do this in R, if he hasn't already.  I haven't thought
610 at all about how these scope issues generalize to, say, bash blocks.
612 Maybe this is something that should be controlled by a header
613 argument?
615 ** =\C-c\C-c= evaluation
617 With org-mode version at least 6.23, see the documentation for
618 [[info:org:Context-sensitive%20commands][info:org:Context-sensitive commands]].
620 ** free explicit variables
621 Maybe we should have some idea of variables independent of any
622 particular type of source code or source block.  These could be
623 variables that have a value inside of the scope of the org-mode file,
624 and they could be used as a transport mechanism for information
625 transfer between org-tables, org-lists, and different source-blocks.
627 Each type of source code (and org-mode types like tables, lists,
628 etc...) would need to implement functions for converting different
629 types of data to and from these variables (which would be elisp
630 variables).
632 So for example say we want to read the values from a table into an R
633 block, perform some calculations, and then write the results back into
634 the table.  We could
635 1) assign the table to a variable
636    - the table would be converted into a lisp vector (list of lists)
637    - the vector would be saved in the variable
638 2) an R source block would reference the variable
639    - the variable would be instantiated into an R variable (through
640      mechanisms mentioned [[* Dan: thinking aloud re: referencing data from R][elsewhere]])
641    - the R code is executed, and the value of the variable *inside of
642      R* is updated
643    - when the R block finished the value of the variable *globally in
644      the org buffer* would be updated
645 3) optionally the global value of the variable would be converted back
646    into an org-mode table and would be used to overwrite the existing
647    table.
649 What do you think?
651 This might not be too different from what we were already talking
652 about, but I think the introduction of the idea of having variables
653 existing independently of any tables or source code blocks is novel
654 and probably has some advantages (and probably shortfalls).
657 * COMMENT Commentary
658 I'm seeing this as like commit notes, and a place for less formal
659 communication of the goals of our changes.
661 ** Eric <2009-02-06 Fri 15:41>
662 I think we're getting close to a comprehensive set of objectives
663 (although since you two are the real R user's I leave that decision up
664 to you).  Once we've agreed on a set of objectives and agreed on at
665 least to broad strokes of implementation, I think we should start
666 listing out and assigning tasks.
668 ** Eric <2009-02-09 Mon 14:25>
669 I've done a fairly destructive edit of this file.  The main goal was
670 to enforce a structure on the document that we can use moving forward,
671 so that any future objective changes are all made to the main
672 objective list.
674 I apologize for removing sections written by other people.  I did this
675 when they were redundant or it was not clear how to fit them into this
676 structure.  Rest assured if the previous text wasn't persisted in git
677 I would have been much more cautious about removing it.
679 I hope that this outline structure should be able to remain stable
680 through the process of fleshing out objectives, and cashing those
681 objectives out into tasks.  That said, please feel free to make any
682 changes that you see fit.
684 ** Dan <2009-02-12 Thu 10:23>
685    Good job Eric with major works on this file.
687 ** Eric <2009-02-22 Sun 13:17>
688 So I skipped ahead and got started on the fun part.  Namely stubbing
689 out some of the basic functionality.  Please don't take any of the
690 decisions I've made so far (on things like names, functionality,
691 design etc...) as final decisions, I'm of course open to and hoping
692 for improvement.
694 So far [[file:org-babel/org-babel.el][org-babel.el]] and [[file:org-babel/org-babel-script.el][org-babel-script.el]] can be used to evaluate source
695 code blocks of simple scripting languages.  It shouldn't be too hard
696 (any takers) to write a org-babel-R.el modeled after org-babel-script.el
697 to use for evaluating R code files.
699 See the [[* org-babel.el beginning functionality][Sandbox]] for evaluable examples.
701 ** Eric <2009-02-23 Mon 15:12>
702 While thinking about how to implement the transfer of data between
703 source blocks and the containing org-mode file, I decided it *might*
704 be useful to explicitly support the existence of variables which exist
705 independent of source blocks or tables.  I'd appreciate any
706 feedback... (see [[free explicit variables][free explicit variables]])
708 ** Eric <2009-02-23 Mon 17:53>
709 So as I start populating this file with source code blocks I figure I
710 should share this... I don't know if you guys use [[http://code.google.com/p/smart-snippet/][yasnippet]] at all,
711 but if you do you might find this [[file:block][block-snippet]] org-mode snippet
712 useful (I use it all the time).
714 ** Dan <2009-05-14 Thu 19:13>
715    Please note that I am at an early stage of learning org-babel /
716    studying the code so I may be misunderstanding things.
717    1. removed prefix arg [[2. evaluate the transpose definition =\C-c\C-c= on the beginning of][here]]
718    2. changed :replace -> replace 
719    3. added some tasks and bugs
720       
722 * Buffer Dictionary
723  LocalWords:  DBlocks dblocks org-babel el eric fontification