14 Working with source code

Source code here refers to any code typed in Org mode documents. Org can
manage source code in any Org file once such code is tagged with begin and
end markers. Working with source code begins with tagging source code
blocks. Tagged ‘src’ code blocks are not restricted to the preamble or
the end of an Org document; they can go anywhere—with a few exceptions,
such as not inside comments and fixed width areas. Here's a sample
‘src’ code block in emacs-lisp:

Org can take the code in the block between the ‘#+BEGIN_SRC’ and
‘#+END_SRC’ tags, and format, compile, execute, and show the results.
Org can simplify many housekeeping tasks essential to modern code
maintenance. That's why these blocks in Org mode literature are sometimes
referred to as ‘live code’ blocks (as compared to the static text and
documentation around it). Users can control how ‘live’ they want each
block by tweaking the headers for compiling, execution, extraction.

Org's ‘src’ code block type is one of many block types, such as quote,
export, verse, latex, example, and verbatim. This section pertains to
‘src’ code blocks between ‘#+BEGIN_SRC’ and ‘#+END_SRC’

For exporting, Org can then extract ‘src’ code blocks into compilable
source files (in a conversion process known as tangling in literate
programming terminology).

For publishing, Org's back-ends can handle the ‘src’ code blocks and the
text for output to a variety of formats with native syntax highlighting.

For executing the source code in the ‘src’ code blocks, Org provides
facilities that glue the tasks of compiling, collecting the results of the
execution, and inserting them back to the Org file. Besides text output,
results may include links to other data types that Emacs can handle: audio,
video, and graphics.

An important feature of Org's execution of the ‘src’ code blocks is
passing variables, functions, and results between ‘src’ blocks. Such
interoperability uses a common syntax even if these ‘src’ blocks are in
different source code languages. The integration extends to linking the
debugger's error messages to the line in the ‘src’ code block in the Org
file. That should partly explain why this functionality by the original
contributors, Eric Schulte and Dan Davison, was called ‘Org Babel’.

In literate programming, the main appeal is code and documentation
co-existing in one file. Org mode takes this several steps further. First
by enabling execution, and then by inserting results of that execution back
into the Org file. Along the way, Org provides extensive formatting
features, including handling tables. Org handles multiple source code
languages in one file, and provides a common syntax for passing variables,
functions, and results between ‘src’ code blocks.

Org mode fulfills the promise of easy verification and maintenance of
publishing reproducible research by keeping all these in the same file: text,
data, code, configuration settings of the execution environment, the results
of the execution, and associated narratives, claims, references, and internal
and external links.

Details of Org's facilities for working with source code are shown next.