rorg.html 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  2. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  3. <html xmlns="http://www.w3.org/1999/xhtml"
  4. lang="en" xml:lang="en">
  5. <head>
  6. <title>rorg &mdash; Code evaluation in org-mode, with an emphasis on R</title>
  7. <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/>
  8. <meta name="generator" content="Org-mode"/>
  9. <meta name="generated" content="2009-02-08 14:56:13 EST"/>
  10. <meta name="author" content="Dan"/>
  11. <style type="text/css">
  12. <!--/*--><![CDATA[/*><!--*/
  13. html { font-family: Times, serif; font-size: 12pt; }
  14. .title { text-align: center; }
  15. .todo { color: red; }
  16. .done { color: green; }
  17. .tag { background-color: #add8e6; font-weight:normal }
  18. .target { }
  19. .timestamp { color: #bebebe; }
  20. .timestamp-kwd { color: #5f9ea0; }
  21. p.verse { margin-left: 3% }
  22. pre {
  23. border: 1pt solid #AEBDCC;
  24. background-color: #F3F5F7;
  25. padding: 5pt;
  26. font-family: courier, monospace;
  27. font-size: 90%;
  28. overflow:auto;
  29. }
  30. table { border-collapse: collapse; }
  31. td, th { vertical-align: top; }
  32. dt { font-weight: bold; }
  33. div.figure { padding: 0.5em; }
  34. div.figure p { text-align: center; }
  35. .linenr { font-size:smaller }
  36. .code-highlighted {background-color:#ffff00;}
  37. .org-info-js_info-navigation { border-style:none; }
  38. #org-info-js_console-label { font-size:10px; font-weight:bold;
  39. white-space:nowrap; }
  40. .org-info-js_search-highlight {background-color:#ffff00; color:#000000;
  41. font-weight:bold; }
  42. /*]]>*/-->
  43. </style>
  44. <script type="text/javascript">
  45. <!--/*--><![CDATA[/*><!--*/
  46. function CodeHighlightOn(elem, id)
  47. {
  48. var target = document.getElementById(id);
  49. if(null != target) {
  50. elem.cacheClassElem = elem.className;
  51. elem.cacheClassTarget = target.className;
  52. target.className = "code-highlighted";
  53. elem.className = "code-highlighted";
  54. }
  55. }
  56. function CodeHighlightOff(elem, id)
  57. {
  58. var target = document.getElementById(id);
  59. if(elem.cacheClassElem)
  60. elem.className = elem.cacheClassElem;
  61. if(elem.cacheClassTarget)
  62. target.className = elem.cacheClassTarget;
  63. }
  64. /*]]>*/-->
  65. </script>
  66. </head><body>
  67. <h1 class="title">rorg &mdash; Code evaluation in org-mode, with an emphasis on R</h1>
  68. <div id="table-of-contents">
  69. <h2>Table of Contents</h2>
  70. <div id="text-table-of-contents">
  71. <ul>
  72. <li><a href="#sec-1">Overview (Dan) </a>
  73. <ul>
  74. <li><a href="#sec-1.1">Project objectives </a>
  75. <ul>
  76. <li><a href="#sec-1.1.1">It produces text/numeric output </a></li>
  77. <li><a href="#sec-1.1.2">It produces graphical output </a></li>
  78. <li><a href="#sec-1.1.3">It creates some non-graphics files </a></li>
  79. <li><a href="#sec-1.1.4">It alters the environment by side effect in some other way </a></li>
  80. </ul>
  81. </li>
  82. <li><a href="#sec-1.2">Implementation questions </a>
  83. <ul>
  84. <li><a href="#sec-1.2.1">How is the code placed in the org file? </a></li>
  85. <li><a href="#sec-1.2.2">When is the code evaluated? </a></li>
  86. <li><a href="#sec-1.2.3">What is the result of code evaluation? </a></li>
  87. </ul></li>
  88. </ul>
  89. </li>
  90. <li><a href="#sec-2">Commentary </a>
  91. <ul>
  92. <li><a href="#sec-2.1">Eric </a></li>
  93. </ul>
  94. </li>
  95. <li><a href="#sec-3">Objectives </a>
  96. <ul>
  97. <li><a href="#sec-3.1">Send data to R from org </a>
  98. <ul>
  99. <li><a href="#sec-3.1.1">Implementations </a></li>
  100. </ul>
  101. </li>
  102. <li><a href="#sec-3.2">Evaluate R code from org and deal with output appropriately </a>
  103. <ul>
  104. <li><a href="#sec-3.2.1">vector output </a></li>
  105. <li><a href="#sec-3.2.2">graphical output </a></li>
  106. </ul>
  107. </li>
  108. <li><a href="#sec-3.3">Evaluate R code on export </a></li>
  109. </ul>
  110. </li>
  111. <li><a href="#sec-4">Notes </a>
  112. <ul>
  113. <li><a href="#sec-4.1">Special editing and evaluation of source code in R blocks </a>
  114. <ul>
  115. <li><a href="#sec-4.1.1">R-block proposal </a></li>
  116. <li><a href="#sec-4.1.2">Source code blocks </a></li>
  117. <li><a href="#sec-4.1.3">dblocks </a></li>
  118. <li><a href="#sec-4.1.4">R blocks </a></li>
  119. </ul>
  120. </li>
  121. <li><a href="#sec-4.2">Interaction with the R process </a></li>
  122. </ul>
  123. </li>
  124. <li><a href="#sec-5">Tasks </a></li>
  125. <li><a href="#sec-6">buffer dictionary </a></li>
  126. </ul>
  127. </div>
  128. </div>
  129. <div id="outline-container-1" class="outline-2">
  130. <h2 id="sec-1">Overview (Dan <span class="timestamp">2009-02-08 Sun</span>) </h2>
  131. <div id="text-1">
  132. </div>
  133. <div id="outline-container-1.1" class="outline-3">
  134. <h3 id="sec-1.1">Project objectives </h3>
  135. <div id="text-1.1">
  136. <p>This project is basically about putting source code into org
  137. files. This isn't just code to look pretty as a source code example,
  138. but code to be evaluated. Org files have 3 main export targets: org,
  139. html and latex. Thus the aim of this project is to produce files in
  140. those formats that have benefitted in some way from the evaluation of
  141. source code that is present in the source org file. We have a current
  142. focus on R code, but we are regarding that more as a working example
  143. than as a defining feature of the project.
  144. </p>
  145. <p>
  146. Code evaluation can have three relevant consequences. Our aim is to
  147. deal with these consequences as follows:
  148. </p>
  149. </div>
  150. <div id="outline-container-1.1.1" class="outline-4">
  151. <h4 id="sec-1.1.1">It produces text/numeric output </h4>
  152. <div id="text-1.1.1">
  153. <p>We (optionally) incorporate the text output as text in the target
  154. document
  155. </p></div>
  156. </div>
  157. <div id="outline-container-1.1.2" class="outline-4">
  158. <h4 id="sec-1.1.2">It produces graphical output </h4>
  159. <div id="text-1.1.2">
  160. <p>We either link to the graphics or (html/latex) include them inline.
  161. </p></div>
  162. </div>
  163. <div id="outline-container-1.1.3" class="outline-4">
  164. <h4 id="sec-1.1.3">It creates some non-graphics files </h4>
  165. <div id="text-1.1.3">
  166. <p>? We link to other file output
  167. </p></div>
  168. </div>
  169. <div id="outline-container-1.1.4" class="outline-4">
  170. <h4 id="sec-1.1.4">It alters the environment by side effect in some other way </h4>
  171. <div id="text-1.1.4">
  172. <p>We bear this in mind
  173. </p>
  174. </div>
  175. </div>
  176. </div>
  177. <div id="outline-container-1.2" class="outline-3">
  178. <h3 id="sec-1.2">Implementation questions </h3>
  179. <div id="text-1.2">
  180. <p>These objectives raise three questions:
  181. </p>
  182. <ol>
  183. <li>
  184. How is the code placed in the org file?
  185. </li>
  186. <li>
  187. When is the code evaluated?
  188. </li>
  189. <li>
  190. What is the result of code evaluation?
  191. </li>
  192. </ol>
  193. </div>
  194. <div id="outline-container-1.2.1" class="outline-4">
  195. <h4 id="sec-1.2.1">How is the code placed in the org file? </h4>
  196. <div id="text-1.2.1">
  197. <p>Using some version of the code block ideas that Eric and Austin
  198. have worked on. (In addition, an aim of org-R was to allow Org
  199. users who are not R users to specify R code implicitly, using
  200. native org syntax. I'd like to maintain that, but it's not central
  201. to this project.)
  202. </p>
  203. </div>
  204. </div>
  205. <div id="outline-container-1.2.2" class="outline-4">
  206. <h4 id="sec-1.2.2">When is the code evaluated? </h4>
  207. <div id="text-1.2.2">
  208. <p>Let's use an asterisk to indicate content which includes the
  209. <b>result</b> of code evaluation, rather than the code itself. Clearly
  210. we have a requirement for the following transformation:
  211. </p>
  212. <p>
  213. org &rarr; org*
  214. </p>
  215. <p>
  216. Let's say this transformation is effected by a function
  217. `org-eval-buffer'. This transformation is necessary when the
  218. target format is org (say you want to update the values in an org
  219. table, or generate a plot and create an org link to it), and it
  220. can also be used as the first step by which to reach html and
  221. latex:
  222. </p>
  223. <p>
  224. org &rarr; org* &rarr; html
  225. </p>
  226. <p>
  227. org &rarr; org* &rarr; latex
  228. </p>
  229. <p>
  230. Thus in principle we can reach our 3 target formats with
  231. `org-eval-buffer', `org-export-as-latex' and `org-export-as-html'.
  232. </p>
  233. <p>
  234. An extra transformation that we might want is
  235. </p>
  236. <p>
  237. org &rarr; latex
  238. </p>
  239. <p>
  240. I.e. export to latex without evaluation of code, in such a way that R
  241. code can subsequently be evaluated using
  242. <code>Sweave(driver=RweaveLatex)</code>, which is what the R community is
  243. used to. This would provide a `bail out' avenue where users can
  244. escape org mode and enter a workflow in which the latex/noweb file
  245. is treated as source.
  246. </p>
  247. <ul>
  248. <li id="sec-1.2.2.1">How do we implement `org-eval-buffer'? <br/>
  249. <p>
  250. AIUI The following can all be viewed as implementations of
  251. org-eval-buffer for R code:
  252. </p>
  253. <ul>
  254. <li id="sec-1.2.2.1.1">org-eval-light <br/>
  255. This is the beginnings of a general evaluation mechanism, that
  256. could evaluate python, ruby, shell, perl, in addition to R.
  257. The header says it's based on org-eval, what is org-eval??
  258. </li>
  259. <li id="sec-1.2.2.1.2">org-R <br/>
  260. This accomplishes org &rarr; org* in elisp by visiting code blocks
  261. and evaluating code using ESS.
  262. </li>
  263. <li id="sec-1.2.2.1.3">RweaveOrg <br/>
  264. This accomplishes org &rarr; org* using R via
  265. <pre class="example">
  266. Sweave("file-with-unevaluated-code.org", driver=RweaveOrg, syntax=SweaveSyntaxOrg)
  267. </pre>
  268. </li>
  269. <li id="sec-1.2.2.1.4">org-exp-blocks.el <br/>
  270. Like org-R, this achieves org &rarr; org* in elisp by visiting code
  271. blocks and using ESS to evaluate R code.
  272. </li>
  273. </ul>
  274. </li>
  275. </ul>
  276. </div>
  277. </div>
  278. <div id="outline-container-1.2.3" class="outline-4">
  279. <h4 id="sec-1.2.3">What is the result of code evaluation? </h4>
  280. <div id="text-1.2.3">
  281. <p>Here we have to consider text/numeric output, and graphical
  282. output. And also the stage at which evaluation occurs
  283. </p><ul>
  284. <li id="sec-1.2.3.1">org &rarr; org* <br/>
  285. <ul>
  286. <li id="sec-1.2.3.1.1">Text / numerical output <br/>
  287. In the case of org &rarr; org*, I would argue that, where
  288. appropriate, it should be stored in org tables. Thus an advantage
  289. our project would have over Sweave is that tabular output is
  290. automatically conveqrted to native tables on export to HTML and
  291. latex.
  292. </li>
  293. <li id="sec-1.2.3.1.2">Graphical output <br/>
  294. We place an org link to the file. This is done already by
  295. org-R-apply, and by RweaveOrg.
  296. </li>
  297. </ul>
  298. </li>
  299. <li id="sec-1.2.3.2">latex &rarr; latex* <br/>
  300. This is done by Sweave(driver=RweaveLatex) and so is out of our hands
  301. </li>
  302. </ul>
  303. </div>
  304. </div>
  305. </div>
  306. </div>
  307. <div id="outline-container-2" class="outline-2">
  308. <h2 id="sec-2">Commentary </h2>
  309. <div id="text-2">
  310. </div>
  311. <div id="outline-container-2.1" class="outline-3">
  312. <h3 id="sec-2.1">Eric <span class="timestamp">2009-02-06 Fri 15:41</span> </h3>
  313. <div id="text-2.1">
  314. <p>I think we're getting close to a comprehensive set of objectives
  315. (although since you two are the real R user's I leave that decision up
  316. to you). Once we've agreed on a set of objectives and agreed on at
  317. least to broad strokes of implementation, I think we should start
  318. listing out and assigning tasks.
  319. </p>
  320. </div>
  321. </div>
  322. </div>
  323. <div id="outline-container-3" class="outline-2">
  324. <h2 id="sec-3">Objectives </h2>
  325. <div id="text-3">
  326. </div>
  327. <div id="outline-container-3.1" class="outline-3">
  328. <h3 id="sec-3.1">Send data to R from org </h3>
  329. <div id="text-3.1">
  330. <p>Org-mode includes orgtbl-mode, an extremely convenient way of using
  331. tabular data in a plain text file. Currently, spreadsheet
  332. functionality is available in org tables using the emacs package
  333. calc. It would be a boon both to org users and R users to allow
  334. org tables to be manipulated with the R programming language. Org
  335. tables give R users an easy way to enter and display data; R gives
  336. org users a powerful way to perform vector operations, statistical
  337. tests, and visualization on their tables.
  338. </p>
  339. </div>
  340. <div id="outline-container-3.1.1" class="outline-4">
  341. <h4 id="sec-3.1.1">Implementations </h4>
  342. <div id="text-3.1.1">
  343. <ul>
  344. <li id="sec-3.1.1.1">naive <br/>
  345. Naive implementation would be to use <code>(org-export-table "tmp.csv")</code>
  346. and <code>(ess-execute "read.csv('tmp.csv')")</code>.
  347. </li>
  348. <li id="sec-3.1.1.2">org-R <br/>
  349. org-R passes data to R from two sources: org tables, or csv
  350. files. Org tables are first exported to a temporary csv file
  351. using <a href="existing_tools/org-R.el">org-R-export-to-csv</a>.
  352. </li>
  353. <li id="sec-3.1.1.3">org-exp-blocks <br/>
  354. org-exp-blocks uses <a href="#sec-3.1.1.3">org-interblock-R-command-to-string</a> to send
  355. commands to an R process running in a comint buffer through ESS.
  356. org-exp-blocks has no support for dumping table data to R process, or
  357. vice versa.
  358. </li>
  359. <li id="sec-3.1.1.4">RweaveOrg <br/>
  360. NA
  361. </li>
  362. </ul>
  363. </div>
  364. </div>
  365. </div>
  366. <div id="outline-container-3.2" class="outline-3">
  367. <h3 id="sec-3.2">Evaluate R code from org and deal with output appropriately </h3>
  368. <div id="text-3.2">
  369. </div>
  370. <div id="outline-container-3.2.1" class="outline-4">
  371. <h4 id="sec-3.2.1">vector output </h4>
  372. <div id="text-3.2.1">
  373. <p>When R code evaluation generates vectors and 2-dimensional arrays,
  374. this should be formatted appropriately in org buffers (orgtbl-mode) as well
  375. as in export targets (html, latex)
  376. </p>
  377. <p>
  378. Agreed, if we can convert the vector data to lists then we can use
  379. the many orgtbl-to-* functions to convert the list to whatever
  380. output format we desire. See `orgtbl-to-orgtbl, `orgtbl-to-latex',
  381. `orgtbl-to-html', `orgtbl-to-csv', etc&hellip;
  382. </p>
  383. <ul>
  384. <li id="sec-3.2.1.1">Implementations <br/>
  385. <ul>
  386. <li id="sec-3.2.1.1.1">org-R <br/>
  387. org-R converts R output (vectors, or matrices / 2d-arrays) to an
  388. org table and stores it in the org buffer, or in a separate org
  389. file (csv output would also be perfectly possible).
  390. </li>
  391. <li id="sec-3.2.1.1.2">org-exp-blocks <br/>
  392. </li>
  393. <li id="sec-3.2.1.1.3">RweaveOrg <br/>
  394. </li>
  395. </ul>
  396. </li>
  397. </ul>
  398. </div>
  399. </div>
  400. <div id="outline-container-3.2.2" class="outline-4">
  401. <h4 id="sec-3.2.2">graphical output </h4>
  402. <div id="text-3.2.2">
  403. <p>R can generate graphical output on a screen graphics device
  404. (e.g. X11, quartz), and in various standard image file formats
  405. (png, jpg, ps, pdf, etc). When graphical output is generated by
  406. evaluation of R code in Org, at least the following two things are desirable:
  407. </p><ol>
  408. <li>
  409. output to screen for immediate viewing is possible
  410. </li>
  411. <li>
  412. graphical output to file is linked to appropriately from the
  413. org file This should have the automatic consequence that it is
  414. included appropriately in subsequent export targets (html,
  415. latex).
  416. </li>
  417. </ol>
  418. <ul>
  419. <li id="sec-3.2.2.1">Implementations <br/>
  420. <ul>
  421. <li id="sec-3.2.2.1.1">org-R <br/>
  422. org-R does (1) if no output file is specified and (2) otherwise
  423. </li>
  424. <li id="sec-3.2.2.1.2">org-exp-blocks <br/>
  425. org-exp-blocks tries to do 2, but I don't think that part was
  426. every really working
  427. </li>
  428. <li id="sec-3.2.2.1.3">RweaveOrg <br/>
  429. </li>
  430. </ul>
  431. </li>
  432. </ul>
  433. </div>
  434. </div>
  435. </div>
  436. <div id="outline-container-3.3" class="outline-3">
  437. <h3 id="sec-3.3">Evaluate R code on export </h3>
  438. <div id="text-3.3">
  439. <p>At first I was leaning towards leaving the exporting to Sweave, but it
  440. seems that once we have evaluation or R working, it will not be
  441. difficult to implement full evaluation of R blocks, one-liners, and
  442. creation of R graphics on export directly in elisp.
  443. </p>
  444. <p>
  445. I think that this would be worth the effort since it would eliminate
  446. the need for using Sweave, and would allow for exportation to any
  447. target format supported by org-mode.
  448. </p>
  449. </div>
  450. </div>
  451. </div>
  452. <div id="outline-container-4" class="outline-2">
  453. <h2 id="sec-4">Notes </h2>
  454. <div id="text-4">
  455. </div>
  456. <div id="outline-container-4.1" class="outline-3">
  457. <h3 id="sec-4.1">Special editing and evaluation of source code in R blocks </h3>
  458. <div id="text-4.1">
  459. <p>Unfortunately org-mode how two different block types, both useful.
  460. In developing RweaveOrg, a third was introduced.
  461. </p>
  462. <p>
  463. Eric is leaning towards using the <code>#+begin_src</code> blocks, as that is
  464. really what these blocks contain: source code. Austin believes
  465. that specifying export options at the beginning of a block is
  466. useful functionality, to be preserved if possible.
  467. </p>
  468. <p>
  469. Note that upper and lower case are not relevant in block headings.
  470. </p>
  471. </div>
  472. <div id="outline-container-4.1.1" class="outline-4">
  473. <h4 id="sec-4.1.1"><span class="todo">PROPOSED</span> R-block proposal </h4>
  474. <div id="text-4.1.1">
  475. <p>I (Eric) propose that we use the syntax of source code blocks as they
  476. currently exist in org-mode with the addition of <b>evaluation</b>,
  477. <b>header-arguments</b>, <b>exportation</b>, <b>single-line-blocks</b>, and
  478. <b>references-to-table-data</b>.
  479. </p>
  480. <ol>
  481. <li>
  482. <b>evaluation</b>: These blocks can be evaluated through <code>\C-c\C-c</code> with
  483. a slight addition to the code already present and working in
  484. <a href="existing_tools/org-eval-light.el">org-eval-light.el</a>. All we should need to add for R support would
  485. be an appropriate entry in <a href="#sec-4.1.1">org-eval-light-interpreters</a> with a
  486. corresponding evaluation function. For an example usinga
  487. org-eval-light see <a href="#sec-4.1.1.1">* src block evaluation w/org-eval-light</a>.
  488. </li>
  489. <li>
  490. <b>header-arguments</b>: These can be implemented along the lines of
  491. Austin's header arguments in <a href="existing_tools/RweaveOrg/org-sweave.el">org-sweave.el</a>.
  492. </li>
  493. <li>
  494. <b>exportation</b>: Should be as similar as possible to that done by
  495. Sweave, and hopefully can re-use some of the code currently present
  496. in <a href="existing_tools/exp-blocks/org-exp-blocks.el ">org-exp-blocks.el</a>.
  497. </li>
  498. <li>
  499. <b>single-line-blocks</b>: It seems that it is useful to be able to
  500. place a single line of R code on a line by itself. Should we add
  501. syntax for this similar to Dan's <code>#+R:</code> lines? I would lean
  502. towards something here that can be re-used for any type of source
  503. code in the same manner as the <code>#+begin_src R</code> blocks, maybe
  504. <code>#+src_R</code>?
  505. </li>
  506. <li>
  507. <b>references-to-table-data</b>: I get this impression that this is
  508. vital to the efficient use of R code in an org file, so we should
  509. come up with a way to reference table data from a single-line-block
  510. or from an R source-code block. It looks like Dan has already done
  511. this in <a href="existing_tools/org-R.el">org-R.el</a>.
  512. </li>
  513. </ol>
  514. <p>What do you think? Does this accomplish everything we want to be able
  515. to do with embedded R source code blocks?
  516. </p>
  517. <ul>
  518. <li id="sec-4.1.1.1">src block evaluation w/org-eval-light <br/>
  519. here's an example using org-eval-light.el
  520. <p>
  521. first load the org-eval-light.el file
  522. </p>
  523. <p>
  524. <i>&lt;elisp:(load (expand-file-name "org-eval-light.el" (expand-file-name "existing_tools" (file-name-directory buffer-file-name))))&gt;</i>
  525. </p>
  526. <p>
  527. then press <code>\C-c\C-c</code> inside of the following src code snippet. The
  528. results should appear in a comment immediately following the source
  529. code block. It shouldn't be too hard to add R support to this
  530. function through the `org-eval-light-interpreters' variable.
  531. </p>
  532. <p>
  533. (Dan: The following causes error on export to HTML hence spaces inserted at bol)
  534. </p>
  535. <p>
  536. #+begin<sub>src</sub> shell
  537. date
  538. #+end<sub>src</sub>
  539. </p>
  540. </li>
  541. </ul>
  542. </div>
  543. </div>
  544. <div id="outline-container-4.1.2" class="outline-4">
  545. <h4 id="sec-4.1.2">Source code blocks </h4>
  546. <div id="text-4.1.2">
  547. <p>Org has an extremely useful method of editing source code and
  548. examples in their native modes. In the case of R code, we want to
  549. be able to use the full functionality of ESS mode, including
  550. interactive evaluation of code.
  551. </p>
  552. <p>
  553. Source code blocks look like the following and allow for the
  554. special editing of code inside of the block through
  555. `org-edit-special'.
  556. </p>
  557. <pre class="src src-r">
  558. ,<span style="color: #add8e6;">## </span><span style="color: #add8e6;">hit C-c ' within this block to enter a temporary buffer in r-mode.
  559. </span>
  560. ,<span style="color: #add8e6;">## </span><span style="color: #add8e6;">while in the temporary buffer, hit C-c C-c on this comment to
  561. </span>,<span style="color: #add8e6;">## </span><span style="color: #add8e6;">evaluate this block
  562. </span>a <span style="color: #98fb98;">&lt;-</span> 3
  563. a
  564. ,<span style="color: #add8e6;">## </span><span style="color: #add8e6;">hit C-c ' to exit the temporary buffer
  565. </span></pre>
  566. </div>
  567. </div>
  568. <div id="outline-container-4.1.3" class="outline-4">
  569. <h4 id="sec-4.1.3">dblocks </h4>
  570. <div id="text-4.1.3">
  571. <p>dblocks are useful because org-mode will automatically call
  572. `org-dblock-write:dblock-type' where dblock-type is the string
  573. following the <code>#+BEGIN:</code> portion of the line.
  574. </p>
  575. <p>
  576. dblocks look like the following and allow for evaluation of the
  577. code inside of the block by calling <code>\C-c\C-c</code> on the header of
  578. the block.
  579. </p>
  580. </div>
  581. </div>
  582. <div id="outline-container-4.1.4" class="outline-4">
  583. <h4 id="sec-4.1.4">R blocks </h4>
  584. <div id="text-4.1.4">
  585. <p>In developing RweaveOrg, Austin created <a href="existing_tools/RweaveOrg/org-sweave.el">org-sweave.el</a>. This
  586. allows for the kind of blocks shown in <a href="existing_tools/RweaveOrg/testing.Rorg">testing.Rorg</a>. These blocks
  587. have the advantage of accepting options to the Sweave preprocessor
  588. following the #+BEGIN<sub>R</sub> declaration.
  589. </p>
  590. </div>
  591. </div>
  592. </div>
  593. <div id="outline-container-4.2" class="outline-3">
  594. <h3 id="sec-4.2">Interaction with the R process </h3>
  595. <div id="text-4.2">
  596. <p>
  597. We should take care to implement this in such a way that all of the
  598. different components which have to interactive with R including:
  599. </p><ul>
  600. <li>
  601. evaluation of source code blocks
  602. </li>
  603. <li>
  604. automatic evaluation on export
  605. </li>
  606. <li>
  607. evaluation of \R{} snippets
  608. </li>
  609. <li>
  610. evaluation of single source code lines
  611. </li>
  612. <li>
  613. sending/receiving vector data
  614. </li>
  615. </ul>
  616. <p>I think we currently have two implementations of interaction with R
  617. processes; <a href="existing_tools/org-R.el">org-R.el</a> and <a href="existing_tools/exp-blocks/org-exp-blocks.el ">org-exp-blocks.el</a>. We should be sure to take
  618. the best of each of these approaches.
  619. </p>
  620. </div>
  621. </div>
  622. </div>
  623. <div id="outline-container-5" class="outline-2">
  624. <h2 id="sec-5">Tasks </h2>
  625. <div id="text-5">
  626. </div>
  627. </div>
  628. <div id="outline-container-6" class="outline-2">
  629. <h2 id="sec-6">buffer dictionary </h2>
  630. <div id="text-6">
  631. <p>LocalWords: DBlocks dblocks
  632. </p></div>
  633. </div>
  634. <div id="postamble"><p class="author"> Author: Dan
  635. <a href="mailto:dan@Tichodroma">&lt;dan@Tichodroma&gt;</a>
  636. </p>
  637. <p class="date"> Date: 2009-02-08 14:56:13 EST</p>
  638. <p>HTML generated by org-mode 6.21trans in emacs 22</p>
  639. </div></body>
  640. </html>