~bzg/worg

ref: 3658c7e8fa00eacda27648e39a3d8e4e65af0340 worg/org-contrib/babel/intro.org -rw-r--r-- 46.4 KiB
3658c7e8Thomas S. Dye org-contrib/babel/intro.org: Put subtrees in order 3 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
#+TITLE:      Introducing Org Babel
#+AUTHOR:     Eric Schulte, Dan Davison, Tom Dye
#+EMAIL:      schulte.eric at gmail dot com, davison at stats dot ox dot ac dot uk, tsd at tsdye dot online
#+OPTIONS:    H:3 num:nil toc:2 \n:nil ::t |:t ^:{} -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
#+LANGUAGE:   en
#+HTML_LINK_UP:  index.html
#+HTML_LINK_HOME: https://orgmode.org/worg

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

* Improving this document					   :noexport:
** TODO Developments
   - org-babel can now cache the results of source block execution to avoid
     rerunning the same calculation.  The cache uses a sha1 hash key of the
     source code body and the header arguments to determine if
     recalculation is required.  These hash keys are kept mostly hidden in
     the #+results line of the results of the block.  This behavior is
     turned off by default.  It is controlled through the :cache
     and :nocache header arguments.  To enable caching on a single block
     add the :cache header argument, to enable global caching change the
     value of your `org-babel-default-header-args' variable as follows

     (setq org-babel-default-header-args
     (cons '(:cache)
     (assq-delete-all :nocache org-babel-default-header-args)))

   - It is now possible to fold results by tabbing on the beginning of the
     #+results line.  This can be done automatically to all results on
     opening of a file by adding the following to your org-mode hook

     (add-hook 'org-mode-hook 'org-babel-result-hide-all)

   - allow header argument values to be lisp forms, for example the
     following is now valid

     :file (format "%s/images/pca-scatter.png" dir)

** TODO Starter kit links in [[#emacs-initialization][this section]] are to an archived project and a deprecated project
Are literate starter kits a thing anymore?
** DONE HTML export of code appears broken in [[#spreadsheet][this section]]
CLOSED: [2021-10-23 Sat 14:19]
It shows the mean as 0.00, when the table above it shows 0.77.
** CANCELED Language specific header arguments
CLOSED: [2021-10-23 Sat 14:11]
- State "CANCELED"   from "TODO"       [2021-10-23 Sat 14:11] \\
  Language specific header arguments are handled elsewhere.  A link is provided in this document.
   -    org-babel: capture graphical output from R

   If a [:file filename.ext] header arg is provided, then all graphical
   output from the source block is captured on disk, and output of the
   source block is a link to the resulting file, as with the
   graphics-only languages such as gnuplot, ditaa, dot, asymptote. An
   attempt is made to find a graphics device corresponding to the file
   extension (currently .png, .jpg, .jpeg, .tiff, .bmp, .pdf, .ps,
   .postscript are recognised); if that fails, png format output is
   created.

   Additionally, values for several arguments to the R graphics
   device can be passed using header args:

   :width :height :bg :units :pointsize
   :antialias :quality :compression :res :type
   :family :title :fonts :version :paper :encoding
   :pagecentre :colormodel :useDingbats :horizontal

   Arguments to the R graphics device that are not supported as header
   args can be passed as a string in R argument syntax, using the header
   arg :R-dev-args

   An example block is (although both bg and fg can be passed directly as
   header args)

   \#+begin_src R :file z.pdf :width 8 :height 8 :R-dev-args bg="olivedrab", fg="hotpink"
   plot(matrix(rnorm(100), ncol=2), type="l")
   \#+end_src

   - Yes, I think we do want a version of this for python and ruby et al. In
   your example, the filename is created in python. I suggest doing it
   slightly differently, something like this.

   #+name: fileoutput
   #+begin_src python :file outfile.txt
 def savetofile(result, filename):
     with open(filename, 'w') as f:
         f.write(str(result))
 savetofile(78, 'outfile.txt')
 55
   #+end_src

   #+results: fileoutput
   [[file:outfile.txt]]

   This functionality is now available for ruby & python in branch
   ded-babel of git://orgmode.org/org-mode/babel.git.

   So here, if you specify :file <filepath> ruby/python blindly outputs a
   link to <filepath>, regardless of the contents of the
   code. Responsibility for creating useful contents of <filepath> lies
   with the code. Notice that with this you have to specify the output file
   twice: once as an org-babel directive, and once in the python code. This
   is in contrast to the graphics languages (dot, ditaa, asymptote), where
   the results *automatically* get sent to the file specified by :file. The
   same is also true now for graphical output from R.

   The difference with python, ruby et al is that they might create file
   output in a variety of ways which we can't anticipate, so we can't
   automatically send output to the file. In contrast, the graphics
   language *always* create file output and always do it in the same
   way. [And in R it is possible to divert all graphical output to file] A
   possible extension of the above might be to use a "magic variable" so
   that a python variable is created e.g. __org_babel_output_file__ that
   always holds a string corresponding to the file specified by :file. Eric
   may have further ideas / views here.

** DONE The Header Arguments section of the manual has been reorganized
CLOSED: [2021-10-23 Sat 14:10]
Now, the header arguments are dispersed through the manual according to function.  Figure out how to replace references to the old manual section.
** DONE Get rid of underscores in tt markup
CLOSED: [2021-10-16 Sat 15:30]
Change =_Ctrl C '_= to =Ctrl C '=
** DONE Example of an [[*In-line Code Blocks][inline code block]] is cryptic
CLOSED: [2021-10-16 Sat 15:26]
Revise the example to approximate the style of the manual.
** DONE #+resname: is deprecated
CLOSED: [2021-10-16 Sat 10:19]
Change #+resname: to #+results: globally.
** DONE The Org manual has a style for meta-information in examples
CLOSED: [2021-10-16 Sat 15:27]
e.g, #+NAME: <name>
Change the meta-information in this document to match the manual style.
** DONE Is it correct to say that Org Babel is pre-populated with LOB in [[#library-of-babel][this section]]?
CLOSED: [2021-10-16 Sat 15:27]
The LOB was moved out of Org and now lives on Worg.  Need to sort this, perhaps with directions on how to install the LOB from Worg.
** DONE HTML export of code appears broken in [[#literate-programming][another section]]
CLOSED: [2021-10-16 Sat 15:28]
Here, the export appears to be missing entirely.
** DONE Remove texttt characters from headings
CLOSED: [2021-10-09 Sat 16:12]
They look small and weird.
** DONE Regularize programming language names
CLOSED: [2021-10-09 Sat 15:15]
Typically, the programming language name is capitalized, even though command line calls to the language are not.  Change language names throughout to recognize this distinction.  NB some programming language names are not capitalized.
** DONE Straighten out ditaa
CLOSED: [2021-10-09 Sat 15:15]
This document assumes it is distributed with Org, which is no longer the case
** DONE #+tblname: is deprecated
CLOSED: [2021-10-09 Sat 12:51]
Change "#+tblname:" to "#+name:"
** DONE Org-mode is now called Org in the manual
CLOSED: [2021-10-09 Sat 12:58]
Change "Org-mode" to "Org".
** DONE The Org manual refers to Babel as Org Babel.
CLOSED: [2021-10-09 Sat 13:02]
Change "Babel" to "Org Babel".
** DONE Org Babel now identifies shell source blocks with =shell=
CLOSED: [2021-10-09 Sat 13:04]
Change "sh" to "shell"
** DONE Document slice indexing of tables
** DONE Document synonymous alternatives
   {call,lob}, {source, function, srcname}, {results, resname}
** DONE Describe useful functions
   - `org-babel-execute-buffer'
   - `org-babel-execute-subtree'

** DONE Language support
   Hopefully we will be breaking out a separate section for
   each language, and expanding the portion which documents the actual
   usage of header-arguments and noweb references as those sections are
   woefully out of date.
** DONE Document noweb references
*** DONE Why is :noweb needed for execution but not for tangling?
** DONE Useful variables
   - # -*- org-src-preserve-indentation: t -*-
** DONE What function is bound to C-c '?
   - this document notes two different functions
* Preamble
  :PROPERTIES:
  :CUSTOM_ID: introduction
  :END:

  Org Babel is about letting [[file:languages/index.org][many different languages]] work together.
  Programming languages live in blocks inside natural language [[https://orgmode.org/][Org]]
  documents.  A piece of data might pass from an Org table to a
  =Python= code block, then maybe move on to an =R= code block, and
  finally end up embedded as a value in the middle of a paragraph or
  possibly pass through a =Gnuplot= code block and end up as a plot
  embedded in the document.

  Through extending [[https://orgmode.org/][Org]] with several features for editing, exporting,
  and executing source code, Org Babel transforms Org into a tool for
  literate programming and reproducible research.

  Org Babel augments [[https://orgmode.org/manual/Working-with-Source-Code.html][Org code blocks]] by providing:

  - interactive and programmatic execution of code blocks;
  - code blocks as functions that accept parameters, refer to
    other code blocks, and can be called remotely; and
  - export to files for literate programming.

* Overview
  Org Babel provides new features on a few different fronts, and
  different people may want to start in different places.

  - Using 'src' blocks in Org mode ::
       If you are not familiar with creating 'src' blocks in an Org
    buffer, and moving between that buffer and the language major-mode
    edit buffer, then you should have a look at [[https://orgmode.org/manual/Literal-Examples.html#Literal-Examples][Org manual]] and Section
    [[#source-code-blocks]], try it out, and come back.
  - Executing code ::
       The core of Org Babel is its ability to execute code in Org
       'src' blocks, taking input from other blocks and tables, with
       output to further blocks and tables. This is described in Section
       [[#source-code-execution]].
  - Literate programming ::
       If you are a programmer writing code that you would normally
       execute in some other way (e.g. from the command line, or sourcing
       it into an interactive session), then a simple introduction to
       Org Babel is to place your code in blocks in an Org file, and to
       use Org Babel's [[#literate-programming][Literate Programming]] support to extract pure code
       from your Org files.

  All of these use cases, as well as exhaustive documentation of the
  features of Org Babel are covered in the [[https://orgmode.org/manual/Working-with-Source-Code.html][Working with Source Code]]
  section of the Org manual.

* Configuring Org Babel
  :PROPERTIES:
  :CUSTOM_ID: getting-started
  :results:  silent
  :END:

  If you have a working Emacs installation, then getting started with
  Org Babel is a simple process.

  1) If you are running Emacs24 or later a version of Org with Org
     Babel is already available by default. As of Org 7.0, Org Babel
     is included as part of Org.  If you would like to use a more
     recent Org Babel than the one that ships with your Emacs, then
     please follow [[https://orgmode.org/manual/Installation.html#Installation][these instructions]].

  2) Optionally, activate the subset of languages that you want to use
     with Org Babel.  See the instructions in Section [[file:languages/index.org::#configure][Activate a
     Language]].  Note that Emacs Lisp is activated by default so this
     step can be skipped if you intend to work exclusively with it.

  3) If you have made changes to your setup, please remember to evaluate
     modified configuration file(s).

* Code Blocks
  :PROPERTIES:
  :CUSTOM_ID: source-code-blocks
  :END:

** Code Blocks in Org
   :PROPERTIES:
   :CUSTOM_ID: source-code-blocks-org
   :END:

   Org Babel is all about code blocks in Org. If you are unfamiliar
   with the notion of a code block in Org, where they are called 'src'
   blocks, please have a look at the [[https://orgmode.org/manual/Literal-Examples.html#Literal-Examples][Org manual]] before proceeding.

   Code blocks in supported languages can occur anywhere in an
   Org file.  Code blocks can be entered directly into the
   Org file, but it is often easier to enter code with the
   function =org-edit-src-code=, which is called with the keyboard
   shortcut, =C-c '=.  This places the code block in a new buffer with
   the appropriate mode activated.

   #+begin_src org
  ,#+begin_src <language> <switches> 
  ,<body>
  ,#+end_src
   #+end_src

   For example, a code block of [[http://www.ruby-lang.org/][Ruby]] code looks like this in
   an Org file:

   #+begin_src org
  ,#+begin_src ruby
  ,require 'date'
  ,"This file was last evaluated on #{Date.today}"
  ,#+end_src
   #+end_src

** Code Blocks in Org Babel
   :PROPERTIES:
   :CUSTOM_ID: source-code-blocks-babel
   :END:

   Org Babel adds some new elements to code blocks. The basic
   structure becomes:

   #+begin_src org
  ,#+begin_src <language>  <switches> <header arguments>
  ,<body>
  ,#+end_src
   #+end_src

   - <language> :: The language of the code in the source-code
     block. Valid values must be members of =org-babel-interpreters=.
   - <switches> :: Control code execution, export, and format.     
   - <header arguments> :: Header arguments control many facets of
     code block behavior, including [[https://orgmode.org/manual/Header-arguments.html#Header-arguments][tangling]], [[https://orgmode.org/manual/Evaluating-Code-Blocks.html][evaluation]], handling
     [[https://orgmode.org/manual/Results-of-Evaluation.html][results of evaluation]], and [[https://orgmode.org/manual/Exporting-Code-Blocks.html][exporting]].  In addition, the language
     of the code block might define additional header arguments (see
     [[https://orgmode.org/worg/org-contrib/babel/languages/index.html][Babel: Languages]]).
   - <body> :: The source code to be evaluated.  An important
     key-binding is =C-c '=.  This calls =org-edit-src-code=, a
     function that brings up an edit buffer containing the code using
     the Emacs major mode appropriate to the language.  You can edit
     your code block as you regularly would in Emacs.

* Executing Source Code
  :PROPERTIES:
  :CUSTOM_ID: source-code-execution
  :END:

  Org Babel executes code blocks for *interpreted* languages such
  as =shell=, =Python=, =R=, etc. by passing code to the interpreter, which
  must be installed on your system.  You control what is done with the
  results of execution.

Here are examples of code blocks in four different languages,
followed by their output. If you are viewing the Org version of
this document in Emacs, place point anywhere inside a block and press
=C-c C-c= to run the code[fn:1] (and feel free to alter it!).
** Ruby
In the Org file:
: #+begin_src ruby
: "This block was last evaluated on #{Date.today}"
: #+end_src

HTML export of code:
#+begin_src ruby
"This block was last evaluated on #{Date.today}"
#+end_src

HTML export of the resulting string:
#+results:
: This block was last evaluated on 2009-08-09

** Shell
In the Org file:
: #+begin_src shell
:   echo "This file takes up `du -h org-babel.org |sed 's/\([0-9k]*\)[ ]*org-babel.org/\1/'`"
: #+end_src

HTML export of code:
#+begin_src shell
echo "This file takes up `du -h org-babel.org |sed 's/\([0-9k]*\)[ ]*org-babel.org/\1/'`"
#+end_src

HTML export of the resulting string:
#+RESULTS:
: This file takes up 4.0K

** R
What are the most common words in this file?

In the Org file:
: #+begin_src R :colnames yes
:   words <- tolower(scan("intro.org", what="", na.strings=c("|",":")))
:   t(sort(table(words[nchar(words) > 3]), decreasing=TRUE)[1:10])
: #+end_src

HTML export of code:

#+name: r-tutorial-example
#+begin_src R :colnames yes :exports both
words <- tolower(scan("intro.org", what="", na.strings=c("|",":")))
t(sort(table(words[nchar(words) > 3]), decreasing=TRUE)[1:10])
#+end_src

HTML export of the resulting table:

#+RESULTS: r-tutorial-example
| code | #+end_src | #+name: | #+begin_src | babel | with | block | this | that | blocks |
|------+-----------+---------+-------------+-------+------+-------+------+------+--------|
|   90 |        47 |      45 |          44 |    43 |   43 |    41 |   37 |   36 |     27 |

** ditaa

    In the Org file:
    : #+begin_src ditaa :file blue.png :cmdline -r
    : +---------+
    : | cBLU    |
    : |         |
    : |    +----+
    : |    |cPNK|
    : |    |    |
    : +----+----+
    : #+end_src

    HTML export of code:
    #+name: ditaa-blue
    #+header: :exports both
    #+begin_src ditaa :file ../../images/babel/blue.png :cmdline -r
+---------+
| cBLU    |
|         |
|    +----+
|    |cPNK|
|    |    |
+----+----+
    #+end_src

    HTML export of the resulting image:
    #+RESULTS: ditaa-blue
    [[file:../../images/babel/blue.png]]

* Capturing the Results of Code Evaluation
   :PROPERTIES:
   :CUSTOM_ID: results
   :END:
   Org Babel provides two fundamentally different modes for capturing
   the results of code evaluation: functional mode and scripting
   mode.  The choice of mode is specified by the =:results= header
   argument.
** Functional Mode
    :PROPERTIES:
    :CUSTOM_ID: results-value
    :END:
    The 'result' of code evaluation is the *value* of the last
    statement in the code block. In functional mode, the code block is
    a function with a return value. Functional mode is indicated by
    setting the header argument =:results value=.

    The return value of one code block can be used as input for
    another code block, even one in a different language.  In this
    way, Org Babel becomes a [[#meta-programming-language][meta-programming language]]. If the block
    returns tabular data (a vector, array or table of some sort) then
    this will be held as an Org table in the buffer. This setting is
    the default.

    For example, consider the following block of python code and its
    output.

    #+name: python-tutorial-functional-mode
    #+begin_src python :results value :exports both
import time
print("Hello, today's date is %s" % time.ctime())
print('Two plus two is')
return 2 + 2
    #+end_src

    #+RESULTS: python-tutorial-functional-mode
    : 4

    Notice that, in functional mode, the output consists of the value of
    the last statement and nothing else.

** Scripting Mode
    :PROPERTIES:
    :CUSTOM_ID: results-output
    :END:

    In scripting mode, Org Babel captures the text output of the code
    block and places it in the Org buffer.  Scripting mode is
    indicated by setting the header argument =:results output=.

    It is called scripting mode because the code block contains a
    series of commands, and the output of each command is
    returned. Unlike functional mode, the code block itself has no
    return value apart from the output of the commands it
    contains.[fn:2]

    Consider the result of evaluating this code block with
    scripting mode.

    #+name: python-tutorial-scripting-mode
    #+begin_src python :results output :exports both
import time
print("Hello, today's date is %s" % time.ctime())
print('Two plus two is')
2 + 2
    #+end_src

    #+RESULTS: python-tutorial-scripting-mode
    : Hello, today's date is Sat Oct 16 10:48:47 2021
    : Two plus two is

    Here, scripting mode returned the text that python sent to
    =stdout= with the two =print()= statements.  Because the code
    block doesn't include a =print()= statement for the last value,
    =(2 + 2)=, 4 does not appear in the results.

* Session-based Evaluation
   For some languages, such as =Python=, =R=, =Ruby= and =shell=, it is
   possible to run an interactive session as an "inferior process"
   within Emacs. This means that an environment is created containing
   data objects that persist between different source code
   blocks. Org Babel supports evaluation of code within such sessions
   with the =:session= header argument. If the header argument is
   given a value then that will be used as the name of the session.
   Thus, it is possible to run separate simultaneous sessions in the
   same language.

   Session-based evaluation is particularly useful for prototyping and
   debugging.  The function =org-babel-pop-to-session= can be used to
   switch to the session buffer.

   Once a code block is finished, it is often best to execute it
   outside of a session, so the state of the environment in which it
   executes will be certain.

   With =R=, the session will be under the control of [[http://ess.r-project.org/][Emacs Speaks
   Statistics]] as usual, and the full power of =ESS= is thus still
   available, both in the =R= session, and when switching to the =R=
   code edit buffer with =​C-c '​=.

* Arguments to Code Blocks
   :PROPERTIES:
   :CUSTOM_ID: arguments-to-source-code-blocks
   :END:
   Org Babel supports parameterisation of code blocks, i.e.,
   arguments can be passed to code blocks, which gives them
   the status of *functions*. Arguments can be passed to code blocks in
   both functional and scripting modes.

** Using a Code Block as a Function

    First let's look at a very simple example. The following source
    code block defines a function, using python, that squares its argument.

    #+name: square
    #+header: :var x=0 :exports code 
    #+begin_src python
return x*x
    #+end_src

    In the Org file, the function looks like this:
    : #+name: square
    : #+header: :var x=0
    : #+begin_src python
    : return x*x
    : #+end_src

    Now we use the source block (for information on the =#+call:= syntax see [[#library-of-babel][Library of Babel]]):

    : #+call: square(x=6)

    #+name: call-square
    #+call: square(x=6)

    #+RESULTS: call-square
    : 36

** Using an Org Table as Input

    In this example we define a function called =fibonacci-seq=, using
    Emacs Lisp.  The function =fibonacci-seq= computes a Fibonacci
    sequence.  The function takes a single argument, in this case, a
    reference to an Org table.

    Here is the Org table that is passed to =fibonacci-seq=:

    #+name: fibonacci-inputs
    | 1 | 2 | 3 | 4 |  5 |  6 |  7 |  8 |  9 | 10 |
    | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |

    The table looks like this in the Org buffer:
    : #+name: fibonacci-inputs
    : | 1 | 2 | 3 | 4 |  5 |  6 |  7 |  8 |  9 | 10 |
    : | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |

    The [[http://www.gnu.org/software/emacs/manual/elisp.html][Emacs Lisp]] source code:
    #+name: fibonacci-seq
    #+begin_src emacs-lisp :var fib-inputs=fibonacci-inputs :exports both
  (defun fibonacci (n)
    (if (or (= n 0) (= n 1))
        n
      (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))

  (mapcar (lambda (row)
            (mapcar #'fibonacci row)) fib-inputs)
    #+end_src

    In the Org buffer the function looks like this:
    : #+name: fibonacci-seq
    : #+begin_src emacs-lisp :var fib-inputs=fibonacci-inputs 
    :   (defun fibonacci (n)
    :     (if (or (= n 0) (= n 1))
    :         n
    :       (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
    :
    :   (mapcar (lambda (row)
    :             (mapcar #'fibonacci row)) fib-inputs)
    : #+end_src

    The return value of =fibonacci-seq= is a table:
    #+RESULTS: fibonacci-seq
    | 1 | 1 | 2 |  3 |  5 |   8 |  13 |  21 |   34 |   55 |
    | 1 | 3 | 8 | 21 | 55 | 144 | 377 | 987 | 2584 | 6765 |

* In-line Code Blocks
   Code can be evaluated in-line using the following syntax:

   : Without header args: src_<lang>{<code>} or with header args: src_<lang[<args>]{<code>},
   : for example src_python[:session]{10*x}, where x is a variable existing in the
   : python session.

* Code Block Body Expansion
   Org Babel "expands" code blocks prior to evaluation, i.e., the
   evaluated code comprises the code block contents augmented with
   code that assigns referenced data to variables. It is possible to
   preview expanded contents, and also to expand code during
   tangling.  Expansion takes into account header arguments and
   variables.

   - preview :: The shortcut, =C-c M-b p=, is bound to the function,
     =org-babel-expand-src-block=.  It can be used inside a code block
     to preview the expanded contents. This facility is useful for
     debugging.

   - tangling :: The expanded body can be tangled.  Tangling this way
     includes variable values that may be
	- the results of other code blocks,
	- variables stored in headline properties, or
	- tables.

	One possible use for tangling expanded code block is for =Emacs=
	initialization.  Values such as user names and passwords can be
	stored in headline properties or in tables.  The =:no-expand=
	header argument can be used to inhibit expansion of a code block
	during tangling.

   Here is an example of a code block and its resulting expanded body.

   The data are kept in a table:
   #+name: user-data
   | username | john-doe |
   | password | abc123   |

   The code block refers to the data table:
   #+name: setup-my-account
   #+begin_src emacs-lisp :rownames yes :var data=user-data
  (setq my-special-username (first (first data)))
  (setq my-special-password (first (second data)))
   #+end_src

   With point inside the code block, =C-c M-b p= expands the contents:
   #+begin_src emacs-lisp
  (let ((data (quote (("john-doe") ("abc123")))))
  (setq my-special-username (first (first data)))
  (setq my-special-password (first (second data)))
  )
   #+end_src

* A Meta-Programming Language for Org
   :PROPERTIES:
   :CUSTOM_ID: meta-programming-language
   :END:

   Because the return value of a function written in one language can be
   passed to a function written in another language, or to an Org
   table, which is itself programmable, Org Babel can be used as a
   meta-functional programming language.  With Org Babel, functions from
   many languages can work together.  You can mix and match languages,
   using each language for the tasks to which it is best suited.

   For example, let's take some system diagnostics in the shell and graph them with R.

   First, create a code block, using shell code, to list directories
   in our home directory together with their sizes. Org Babel
   automatically converts the output into an Org table.
      
   : #+name: directories
   : #+begin_src shell :results replace
   :   cd ~ && du -sc * |grep -v total
   : #+end_src
   
   #+name: directories
   #+results: directories
   |       72 | "Desktop"   |
   | 12156104 | "Documents" |
   |  3482440 | "Downloads" |
   |  2901720 | "Library"   |
   |    57344 | "Movies"    |
   | 16548024 | "Music"     |
   |      120 | "News"      |
   |  7649472 | "Pictures"  |
   |        0 | "Public"    |
   |   152224 | "Sites"     |
   |        8 | "System"    |
   |       56 | "bin"       |
   |  3821872 | "mail"      |
   | 10605392 | "src"       |
   |     1264 | "tools"     |
   
   Next write a function with a single line of R code that plots the
   data in the Org table as a dot chart. Note how this code block uses
   the =name= of the previous code block to obtain the data.

   In the Org file:
   : #+name: directory-dot-chart
   : #+header: :var dirs=directories() :exports both
   : #+begin_src R :results graphics file :file ../../images/babel/dirs.png
   :   dotchart(dirs[,1], labels = dirs[,2])
   : #+end_src

   HTML export of code:
   #+name: directory-dot-chart
   #+header: :var dirs=directories :exports both
   #+begin_src R :results graphics file :file ../../images/babel/dirs.png
  dotchart(dirs[,1], labels = dirs[,2])
   #+end_src

   #+caption: HTML export of the directories dot chart.
   #+RESULTS: directory-dot-chart
   [[file:../../images/babel/dirs.png]]

* Using Code Blocks in Org Tables
  :PROPERTIES:
  :CUSTOM_ID: spreadsheet
  :END:

  In addition to passing data from tables as [[#arguments-to-source-code-blocks][arguments]] to code blocks,
  and [[#results-value][storing]] results as tables, Org Babel can be used in a third way
  with Org tables. First note that Org's [[https://orgmode.org/manual/The-Spreadsheet.html][spreadsheet]] is able to
  compute cell values from the values of other cells using a =#+TBLFM=
  formula line. In this way, table computations can be carried out
  using [[https://orgmode.org/manual/Formula-syntax-for-Calc.html#Formula-syntax-for-Calc][Calc]] and [[https://orgmode.org/manual/Formula-syntax-for-Lisp.html#Formula-syntax-for-Lisp][Emacs Lisp]].

  What Org Babel adds is the ability to use code blocks (in whatever
  language) in the =#+TBLFM= line to perform the necessary computation.

** Example 1: Data Summaries Using R
    As a simple example, we'll fill in a cell in an Org table with the
    average value of a few numbers. First, let's make some data. The
    following source block creates an Org table filled with five random
    numbers between 0 and 1.

    : #+name: tbl-example-data
    : #+begin_src R
    : runif(n=5, min=0, max=1)
    : #+end_src

    #+name: tbl-example-data
    | 0.836685163900256 |
    | 0.696652316721156 |
    | 0.382423302158713 |
    | 0.987541858805344 |
    | 0.994794291909784 |

    Now we define a source block to calculate the mean of a table column.

    In the Org file:
    : #+name: R-mean
    : #+begin_src R :var x=""
    : colMeans(x)
    : #+end_src

    HTML export of code:
    #+name: R-mean
    #+begin_src R :var x=""
colMeans(x)
    #+end_src

    Finally, we create the table which is going to make use of the R
    code. This is done using the =org-sbe= ('source block evaluate') macro in
    the table formula line.

    In the Org file:
    : #+name: summaries
    : |              mean |
    : |-------------------|
    : | 0.779619386699051 |
    : #+TBLFM: @2$1='(org-sbe "R-mean" (x "tbl-example-data()"))

    HTML export of code:
    #+name: summaries
    | mean |
    |------|
    | 0.78 |
    #+TBLFM: @2$1='(org-sbe "R-mean" (x "tbl-example-data()"));%.2f

    To recalculate the table formula, use C-u C-c C-c in the
    table. Notice that as things stand the calculated value doesn't
    change, because the data (held in the table above named
    =tbl-example-data=) are static. However, if you delete that data table,
    then the reference will be interpreted as a reference to the source
    block responsible for generating the data; each time the table formula
    is recalculated the source block will be evaluated again, and
    therefore the calculated average value will change.

** Example 2: Org Babel Test Suite
    While developing Org Babel, we used a suite of tests implemented
    as a large Org table.  To run the entire test suite we simply
    evaluate the table with C-u C-c C-c: all of the tests are run,
    the results are compared with expectations, and the table is updated
    with results and pass/fail statistics.

    Here's a sample of our test suite.

    In the Org file:

    : #+name: org-babel-tests
    : | functionality    | block        | arg |    expected |     results | pass |
    : |------------------+--------------+-----+-------------+-------------+------|
    : | basic evaluation |              |     |             |             | pass |
    : |------------------+--------------+-----+-------------+-------------+------|
    : | emacs lisp       | basic-elisp  |   2 |           4 |           4 | pass |
    : | shell            | basic-shell  |     |           6 |           6 | pass |
    : | ruby             | basic-ruby   |     |   org-babel |   org-babel | pass |
    : | python           | basic-python |     | hello world | hello world | pass |
    : | R                | basic-R      |     |          13 |          13 | pass |
    : #+TBLFM: $5='(if (= (length $3) 1) (sbe $2 (n $3)) (sbe $2)) :: $6='(if (string= $4 $5) "pass" (format "expected %S but was %S" $4 $5))

    HTML export of code:

    #+name: org-babel-tests
    | functionality    | block        | arg |    expected |     results | pass |
    |------------------+--------------+-----+-------------+-------------+------|
    | basic evaluation |              |     |             |             | pass |
    |------------------+--------------+-----+-------------+-------------+------|
    | emacs lisp       | basic-elisp  |   2 |           4 |           4 | pass |
    | shell            | basic-shell  |     |           6 |           6 | pass |
    | ruby             | basic-ruby   |     |   org-babel |   org-babel | pass |
    | python           | basic-python |     | hello world | hello world | pass |
    | R                | basic-R      |     |          13 |          13 | pass |
    #+TBLFM: $5='(if (= (length $3) 1) (sbe $2 (n $3)) (sbe $2)) :: $6='(if (string= $4 $5) "pass" (format "expected %S but was %S" $4 $5))

*** Code Blocks for Tests

     In the Org file:

     : #+name: basic-elisp(n)
     : #+begin_src emacs-lisp
     : (* 2 n)
     : #+end_src

     HTML export of code:

     #+name: basic-elisp(n=0)
     #+begin_src emacs-lisp
  (* 2 n)
     #+end_src

     In the Org file:
     : #+name: basic-shell
     : #+begin_src shell :results silent
     : expr 1 + 5
     : #+end_src

     HTML export of code:
     #+name: basic-shell
     #+begin_src shell :results silent
  expr 1 + 5
     #+end_src

     In the Org file:
     : #+name: date-simple
     : #+begin_src shell :results silent
     : date
     : #+end_src

     HTML export of code:
     #+name: date-simple
     #+begin_src shell :results silent
  date
     #+end_src

     In the Org file:
     : #+name: basic-ruby
     : #+begin_src ruby :results silent
     : "org-babel"
     : #+end_src

     HTML export of code:
     #+name: basic-ruby
     #+begin_src ruby :results silent
  "org-babel"
     #+end_src

     In the Org file
     : #+name: basic-python
     : #+begin_src python :results silent
     : 'hello world'
     : #+end_src

     HTML export of code:
     #+name: basic-python
     #+begin_src python :results silent
  'hello world'
     #+end_src

     In the Org file:
     : #+name: basic-R
     : #+begin_src R :results silent
     : b <- 9
     : b + 4
     : #+end_src

     HTML export of code:
     #+name: basic-R
     #+begin_src R :results silent
  b <- 9
  b + 4
     #+end_src

* The Library of Babel
  :PROPERTIES:
  :CUSTOM_ID: library-of-babel
  :END:

  (see also [[https://orgmode.org/manual/Library-of-Babel.html#Library-of-Babel][Org manual:Library-of-Babel]])

  As we saw above with the [[*Using a Code Block as a Function][square]] example, once a source block
  function has been defined it can be called using the =#+call:= notation:

  : #+call: square(x=6)

  But what about code blocks that you want to make available to
  every Org buffer?

  In addition to the current buffer, Org Babel searches for
  pre-defined code block functions in files that have been assigned to
  the Library of Babel, a user-extensible collection of source code
  blocks.

# One use for the Library of
#   Babel (not yet done!) will be to provide a choice of data graphing
#   procedures for data held in Org tables, using languages such as
#   =R=, =Gnuplot=, =Asymptote=, etc. If you implement something that might be
#   of use to other Org users, please consider adding it to the
#   Library of Babel; similarly, feel free to request help solving a
#   problem using external code via Org Babel -- there's always a chance
#   that other Org Babel users will be able to contribute some helpful
#   code.

  Once upon a time, Org Mode was distributed with the eponymous
  [[file:library-of-babel.org][Library of Babel]] file.  This file, which includes a wide variety of
  source code blocks for common tasks, is now available at @@html: <a href="https://git.sr.ht/~bzg/worg/tree/master/item/library-of-babel.org">library-of-babel.org</a>@@.

  In practice, you are free to register as many files as you wish to your Library of Babel 
  using the function, =org-babel-lob-ingest=, which is bound to =C-c C-v l=.

  #+name: add-file-to-lob
  #+begin_src emacs-lisp :exports code
  (org-babel-lob-ingest "path/to/file.org")
  #+end_src

  Note that it is possible to pass table values or the output of a
  source-code block to registered Library of Babel functions. It is
  also possible to reference registered Library of Babel functions in
  arguments to code blocks.

* Literate Programming
  :PROPERTIES:
  :CUSTOM_ID: literate-programming
  :END:

  #+begin_quote
  Let us change our traditional attitude to the construction of
  programs: Instead of imagining that our main task is to instruct a
  /computer/ what to do, let us concentrate rather on explaining to
  /human beings/ what we want a computer to do.

  The practitioner of literate programming can be regarded as an
  essayist, whose main concern is with exposition and excellence of
  style. Such an author, with thesaurus in hand, chooses the names of
  variables carefully and explains what each variable means. He or she
  strives for a program that is comprehensible because its concepts have
  been introduced in an order that is best for human understanding,
  using a mixture of formal and informal methods that reinforce each
  other.

  -- Donald Knuth
  #+end_quote

  Org Babel supports [[https://en.wikipedia.org/wiki/Literate_programming][literate programming]] (LP) by allowing the act of
  programming to take place inside an Org document.  The Org
  document can then be exported (*woven* in LP speak) to HTML or LaTeX for
  consumption by a human, and the embedded source code can be extracted
  (*tangled* in LP speak) into structured source code files for
  consumption by a computer.

  To support these operations Org Babel relies on Org's [[https://orgmode.org/manual/Exporting.html#Exporting][ export
  functionality]] for *weaving* documentation, and on the
  =org-babel-tangle= function, which makes use of [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] [[#literate-programming-example][reference
  syntax]], for *tangling* code files.

  The [[#literate-programming-example][following example]] demonstrates the process of *tangling* in
  Org Babel.

** Simple Literate Programming Example (Noweb Syntax)
    :PROPERTIES:
    :CUSTOM_ID: literate-programming-example
    :END:

    Tangling functionality is controlled by the =tangle= family of tangle
    header arguments.  These arguments can be used to turn tangling on or
    off (the default), either for the code block or the Org
    heading level.

    The following code blocks demonstrate how to tangle them into a
    single source code file using =org-babel-tangle=.

    The following two code blocks have no =tangle= header arguments
    and so will not, by themselves, create source code files.  They are
    included in the source code file by the third code block, which
    does have a =tangle= header argument.

    In the Org file:
    : #+name: hello-world-prefix
    : #+begin_src shell :exports none
    :   echo "/-----------------------------------------------------------\\"
    : #+end_src

    HTML export of code:
    #+name: hello-world-prefix
    #+begin_src shell :exports none
  echo "/-----------------------------------------------------------\\"
    #+end_src

    In the Org file
    : #+name: hello-world-postfix
    : #+begin_src shell :exports none
    :   echo "\-----------------------------------------------------------/"
    : #+end_src

    HTML export of code:
    #+name: hello-world-postfix
    #+begin_src shell :exports none
  echo "\-----------------------------------------------------------/"
    #+end_src

    The third code block does have a =tangle= header argument
    indicating the name of the file to which the tangled source code will
    be written.  It also has [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] style references to the two previous
    code blocks.  These references will be expanded during tangling
    to include them in the output file as well.

    In the Org file:
    : #+name: hello-world
    : #+begin_src shell :tangle hello :exports results :noweb yes :results raw
    :   <<hello-world-prefix>>
    :   echo "|                       hello world                         |"
    :   <<hello-world-postfix>>
    : #+end_src

    HTML export of code:
    #+name: hello-world
    #+begin_src shell :tangle hello.sh :exports both :noweb yes :results org
  <<hello-world-prefix>>
  echo "|                       hello world                         |"
  <<hello-world-postfix>>
    #+end_src

    HTML export of results:
    #+RESULTS: hello-world
    #+begin_src org
    /-----------------------------------------------------------\
    |                       hello world                         |
    \-----------------------------------------------------------/
    #+end_src

    Calling =org-babel-tangle= will result in the following shell source
    code being written to the =hello.sh= file:

    #+name: hello-world-output
    #+begin_src shell
#!/usr/bin/env sh

# [[file:~/org/temp/index.org::*Noweb test][hello-world]]

echo "/-----------------------------------------------------------\\"
echo "|                       hello world                         |"
echo "\-----------------------------------------------------------/"
# hello-world ends here
    #+end_src

    In addition, the following Noweb syntax can be used to insert the *results*
    of evaluating a code block, in this case one named =example-block=.

    : # <<example-block()>>

    Any optional arguments can be passed to =example-block()= by placing the
    arguments inside the parentheses following the convention defined when
    calling source block functions (see the [[#library-of-babel][Library of babel]]). For example,

    : # <<example-block(a=9)>>

    sets the value of argument =a= equal to =9=.  Note that
    these arguments are not evaluated in the current source-code
    block but are passed literally to =example-block()=.

** Emacs Initialization with Org Babel
    :PROPERTIES:
    :CUSTOM_ID: emacs-initialization
    :END:

    #+attr_html: style="float:left;"
    [[file:../../images/babel/dot-emacs.png]]

    Org Babel has special support for embedding your Emacs initialization
    into Org files.  The =org-babel-load-file= function can be used
    to load the Emacs Lisp code blocks embedded in a literate
    Org file in the same way that you might load a regular Emacs Lisp
    file, such as .emacs.

    This allows you to make use of the nice features of Org, such as folding, tags,
    notes, HTML export, etc., to organize and maintain your Emacs initialization.

    To try this out, either see the simple [[#literate-emacs-init][Literate Emacs Initialization]]
    example, or check out the Org Babel Literate Programming version of
    Phil Hagelberg's excellent [[http://github.com/technomancy/emacs-starter-kit/tree/master][emacs-starter-kit]] available at
    [[http://github.com/eschulte/emacs-starter-kit/tree/master][Org-babel-emacs-starter-kit]].

*** Literate Emacs Initialization
      :PROPERTIES:
      :CUSTOM_ID: literate-emacs-init
      :END:

      For a simple example of usage, follow these 5 steps:

      1) create a directory named =.emacs.d= in the base of your home
	 directory;
	 #+begin_src shell
	 mkdir ~/.emacs.d
	 #+end_src
      2) checkout the latest version of Org into the src subdirectory
	 of this new directory;
	 #+begin_src shell
	 cd ~/.emacs.d
	 mkdir src
	 cd src
	 git clone https://git.savannah.gnu.org/git/emacs/org-mode.git
	 #+end_src
      3) place the following code block in a file called =init.el= in your Emacs
	 initialization directory (=~/.emacs.d=).
	 #+name: emacs-init
	 #+begin_src emacs-lisp
	   ;;; init.el --- Where all the magic begins
	   ;;
	   ;; This file loads Org and then loads the rest of our Emacs initialization from Emacs lisp
	   ;; embedded in literate Org files.

	   ;; Load up Org Mode and (now included) Org Babel for elisp embedded in Org Mode files
	   (setq dotfiles-dir (file-name-directory (or (buffer-file-name) load-file-name)))

	   (let* ((org-dir (expand-file-name
			    "lisp" (expand-file-name
				    "org" (expand-file-name
					   "src" dotfiles-dir))))
		  (org-contrib-dir (expand-file-name
				    "lisp" (expand-file-name
					    "contrib" (expand-file-name
						       ".." org-dir))))
		  (load-path (append (list org-dir org-contrib-dir)
				     (or load-path nil))))
	     ;; load up Org and Org-babel
	     (require 'org)
	     (require 'ob-tangle))

	   ;; load up all literate org-mode files in this directory
	   (mapc #'org-babel-load-file (directory-files dotfiles-dir t "\\.org$"))

	   ;;; init.el ends here
	 #+end_src
      4) implement all of your Emacs customizations inside of Emacs Lisp
	 code blocks embedded in Org files in this directory;
	 and
      5)  re-start Emacs to load the customizations.

* Reproducible Research
  :PROPERTIES:
  :CUSTOM_ID: reproducible-research
  :END:
  #+begin_quote
  An article about computational science in a scientific publication is
  not the scholarship itself, it is merely advertising of the
  scholarship. The actual scholarship is the complete software
  development environment and the complete set of instructions which
  generated the figures.

  -- D. Donoho
  #+end_quote

  [[http://reproducibleresearch.net/][Reproducible research]] (RR) is the practice of distributing, along with
  a research publication, all data, software source code, and tools
  required to reproduce the results discussed in the publication.  As
  such the RR package not only describes the research and its results,
  but becomes a complete laboratory in which the research can be
  reproduced and extended.

  Org already has exceptional support for [[https://orgmode.org/manual/Exporting.html#Exporting][exporting to HTML and
  LaTeX]].  Org Babel makes Org a tool for RR by *activating* the data
  and code blocks embedded in Org documents; the entire document
  becomes executable.  This makes it possible, and natural, to
  distribute research in a format that encourages readers to recreate
  results and perform their own analyses.

  One notable existing RR tool is [[https://en.wikipedia.org/wiki/Sweave][Sweave]], which provides a mechanism for
  embedding [[http://www.r-project.org/][R]] code into LaTeX documents.  Sweave is a mature
  and very useful tool, but we believe that Org Babel has several
  advantages:
  - it supports multiple languages (we're not aware of other RR tools that do this);
  - the [[https://orgmode.org/manual/Exporting.html#Exporting][export process]] is flexible and powerful, including HTML as a
    target in addition to LaTeX; and
  - the document can make use of Org features that support [[https://orgmode.org/manual/Agenda-Views.html][project
    planning]] and [[https://orgmode.org/manual/TODO-Items.html][task management]].

* Footnotes
[fn:1] Calling =C-c C-o= on a code block will open the
block's results in a separate buffer.

[fn:2]  This mode will be familiar to Sweave users.