Home Explore Help
Sign In
swflint
/
org-mode-mirror
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Browse Source

Tom's documentation updates for the new code block syntax

Eric Schulte 14 years ago
parent
1ed12cac1a
commit
a3f781be12
1 changed files with 275 additions and 205 deletions
Unified View Show Diff Stats
  1. 275 205
      doc/org.texi

+ 275 - 205
doc/org.texi
View File 

@@ -11651,19 +11651,26 @@ The following sections describe Org-mode's code block handling facilities.
 
 @section Structure of code blocks
 
 @section Structure of code blocks
 
 @cindex code block, structure
 
 @cindex code block, structure
 
 @cindex source code, block structure
 
 @cindex source code, block structure
 
+@cindex #+NAME
 
+@ciindex #+BEGIN_SRC
 
 
 
-The structure of code blocks is as follows (empty code blocks may be inserted
 
-using Org-mode's @ref{Easy Templates} system):
 
+Live code blocks can be specified with a @samp{src} block or
 
+inline@footnote{Note that @samp{src} blocks may be inserted using Org-mode's
 
+@ref{Easy Templates} system}.  The structure of a @samp{src} block is
 
 
 
 @example
 
 @example
 
-#+srcname: <name>
 
-#+begin_src <language> <switches> <header arguments>
 
+#+NAME: <name>
 
+#+BEGIN_SRC <language> <switches> <header arguments>
 
   <body>
 
   <body>
 
-#+end_src
 
+#+END_SRC
 
 @end example
 
 @end example
 
 
 
-Switches and header arguments are optional.  Code can also be embedded in text
 
-inline using
 
+The @code{#+NAME:} line is optional, and can be used to name the code
 
+block. Live code blocks require that a language be specified on the
 
+@code{#+BEGIN_SRC} line.  Switches and header arguments are optional.
 
+@cindex source code, inline
 
+
 
+Live code blocks can also be specified inline using
 
 
 
 @example
 
 @example
 
 src_<language>@{<body>@}
 
 src_<language>@{<body>@}
 
@@ -11676,26 +11683,30 @@ src_<language>[<header arguments>]@{<body>@}
 
 @end example
 
 @end example
 
 
 
 @table @code
 
 @table @code
 
-@item <name>
 
-This name is associated with the code block.  This is similar to the
 
-@samp{#+tblname} lines that can be used to name tables in Org-mode files.
 
-Referencing the name of a code block makes it possible to evaluate the
 
-block from other places in the file, other files, or from Org-mode table
 
-formulas (see @ref{The spreadsheet}).  Names are assumed to be unique by
 
-evaluation functions and the behavior of multiple blocks of the same name is
 
+@item <#+NAME: name>
 
+This line associates a name with the code block.  This is similar to the
 
+@code{#+TBLNAME: NAME} lines that can be used to name tables in Org-mode
 
+files.  Referencing the name of a code block makes it possible to evaluate
 
+the block from other places in the file, from other files, or from Org-mode
 
+table formulas (see @ref{The spreadsheet}).  Names are assumed to be unique
 
+and the behavior of Org-mode when two or more blocks share the same name is
 
 undefined.
 
 undefined.
 
+@cindex #+NAME
 
 @item <language>
 
 @item <language>
 
-The language of the code in the block.
 
+The language of the code in the block (see @ref{Languages}).
 
+@cindex source code, language
 
 @item <switches>
 
 @item <switches>
 
-Optional switches controlling exportation of the code block (see switches discussion in
 
+Optional switches control code block export (see the discussion of switches in
 
 @ref{Literal examples})
 
 @ref{Literal examples})
 
+@cindex source code, switches
 
 @item <header arguments>
 
 @item <header arguments>
 
 Optional header arguments control many aspects of evaluation, export and
 
 Optional header arguments control many aspects of evaluation, export and
 
-tangling of code blocks.  See the @ref{Header arguments}.
 
+tangling of code blocks (see @ref{Header arguments}).
 
 Header arguments can also be set on a per-buffer or per-subtree
 
 Header arguments can also be set on a per-buffer or per-subtree
 
 basis using properties.
 
 basis using properties.
 
+@item source code, header arguments
 
 @item <body>
 
 @item <body>
 
-The source code.
 
+Source code in the specified language.
 
 @end table
 
 @end table
 
 
 
 @comment  node-name,  next,  previous,  up
 
 @comment  node-name,  next,  previous,  up
 
@@ -11744,12 +11755,12 @@ variable @code{org-src-fontify-natively}.
 
 @cindex code block, exporting
 
 @cindex code block, exporting
 
 @cindex source code, exporting
 
 @cindex source code, exporting
 
 
 
-It is possible to export the @emph{contents} of code blocks, the
 
-@emph{results} of code block evaluation, @emph{neither}, or @emph{both}.  For
 
-most languages, the default exports the contents of code blocks.  However, for
 
-some languages (e.g.@: @code{ditaa}) the default exports the results of code
 
-block evaluation.  For information on exporting code block bodies, see
 
-@ref{Literal examples}.
 
+It is possible to export the @emph{code} of code blocks, the @emph{results}
 
+of code block evaluation, @emph{both} the code and the results of code block
 
+evaluation, or @emph{none}.  For most languages, the default exports code.
 
+However, for some languages (e.g.@: @code{ditaa}) the default exports the
 
+results of code block evaluation.  For information on exporting code block
 
+bodies, see @ref{Literal examples}.
 
 
 
 The @code{:exports} header argument can be used to specify export
 
 The @code{:exports} header argument can be used to specify export
 
 behavior:
 
 behavior:
 
@@ -11827,14 +11838,15 @@ of tangled code files.
 
 @cindex source code, evaluating
 
 @cindex source code, evaluating
 
 
 
 Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
 
 Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
 
-potential for that code to do harm.  Org-mode provides a number of safeguards
 
-to ensure that it only evaluates code with explicit confirmation from the
 
-user.  For information on these safeguards (and on how to disable them) see
 
-@ref{Code evaluation security}.} and the results placed in the Org-mode
 
-buffer.  By default, evaluation is only turned on for @code{emacs-lisp} code
 
-blocks, however support exists for evaluating blocks in many languages.  See
 
-@ref{Languages} for a list of supported languages.  See @ref{Structure of
 
-code blocks} for information on the syntax used to define a code block.
 
+potential for that code to do harm.  Org-mode provides safeguards to ensure
 
+that code is only evaluated after explicit confirmation from the user.  For
 
+information on these safeguards (and on how to disable them) see @ref{Code
 
+evaluation security}.} and the results of evaluation optionally placed in the
 
+Org-mode buffer.  By default, the evaluation facility is only enabled for
 
+Lisp code blocks specified as @code{emacs-lisp}. However, souce code blocks
 
+in many languages can be evaluated within Org-mode (see @ref{Languages} for a
 
+list of supported languages and @ref{Structure of code blocks} for
 
+information on the syntax used to define a code block).
 
 
 
 @kindex C-c C-c
 
 @kindex C-c C-c
 
 There are a number of ways to evaluate code blocks.  The simplest is to press
 
 There are a number of ways to evaluate code blocks.  The simplest is to press
 
@@ -11843,63 +11855,51 @@ There are a number of ways to evaluate code blocks.  The simplest is to press
 
 evaluation from the @kbd{C-c C-c} key binding.}.  This will call the
 
 evaluation from the @kbd{C-c C-c} key binding.}.  This will call the
 
 @code{org-babel-execute-src-block} function to evaluate the block and insert
 
 @code{org-babel-execute-src-block} function to evaluate the block and insert
 
 its results into the Org-mode buffer.
 
 its results into the Org-mode buffer.
 
+@cindex #+CALL
 
 
 
 It is also possible to evaluate named code blocks from anywhere in an
 
 It is also possible to evaluate named code blocks from anywhere in an
 
-Org-mode buffer or an Org-mode table.  @code{#+call} (or synonymously
 
-@code{#+function} or @code{#+lob}) lines can be used to remotely execute code
 
-blocks located in the current Org-mode buffer or in the ``Library of Babel''
 
-(see @ref{Library of Babel}).  These lines use the following syntax to place
 
-a call on a line by itself.
 
+Org-mode buffer or an Org-mode table. Live code blocks located in the current
 
+Org-mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel})
 
+can be executed.  Named code blocks can be executed with a separate
 
+@code{#+CALL:} line or inline within a block of text.  
+
 
+The syntax of the @code{#+CALL:} line is
 
 
 
 @example
 
 @example
 
-#+call: <name>(<arguments>)
 
-#+call: <name>[<header args>](<arguments>) <header args>
 
+#+CALL: <name>(<arguments>)
 
+#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
 
 @end example
 
 @end example
 
 
 
-The following syntax can be used to place these calls within a block of
 
-prose.
 
+The syntax for inline evaluation of named code blocks is 
 
 
 @example
 
 @example
 
-...prose... call_<name>(<arguments>) ...prose...
 
-...prose... call_<name>[<header args>](<arguments>)[<header args>] ...prose...
 
+... call_<name>(<arguments>) ...
 
+... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
 
 @end example
 
 @end example
 
 
 
 @table @code
 
 @table @code
 
 @item <name>
 
 @item <name>
 
-The name of the code block to be evaluated.
 
+The name of the code block to be evaluated (see @ref{Structure of code blocks}).
 
 @item <arguments>
 
 @item <arguments>
 
 Arguments specified in this section will be passed to the code block.  These
 
 Arguments specified in this section will be passed to the code block.  These
 
-arguments should relate to @code{:var} header arguments in the called code
 
-block expressed using standard function call syntax.  For example if the
 
-original code block named @code{double} has the header argument @code{:var
 
-n=2}, then the call line passing the number four to that block would be
 
-written as @code{#+call: double(n=2)}.
 
-@item <header args>
 
-Header arguments can be placed either inside the call to the code block or at
 
-the end of the line as shown below.
 
-
 
-@example
 
-#+call: code_bloc_name[XXXX](arguments) YYYY
 
-@end example
 
-
 
-Header arguments located in these two locations are treated differently.
 
-
 
-@table @code
 
-@item XXXX
 
-Those placed in the @code{XXXX} location are passed through and applied to
 
-the code block being called.  These header arguments affect how the code
 
-block is evaluated, for example @code{[:results output]} will collect the
 
-results from @code{STDOUT} of the called code block.
 
-@item YYYY
 
-Those placed in the @code{YYYY} location are applied to the call line and do
 
-not affect the code block being called.  These header arguments affect how
 
-the results are incorporated into the Org-mode buffer when the call line is
 
-evaluated, and how the call line is exported.  For example @code{:results
 
-org} at the end of the call line will insert the results of the call line
 
-inside of an Org-mode block.
 
-@end table
 
-
 
-For more examples of passing header arguments to @code{#+call:} lines see
 
+arguments use standard function call syntax, rather than
 
+header argument syntax.  For example, a @code{#+CALL:} line that passes the
 
+number four to a code block named @code{double}, which declares the header
 
+argument @code{:var n=2}, would be written as @code{#+CALL: double(n=4)}.
 
+@item <inside header arguments>
 
+Inside header arguments are passed through and applied to the named code
 
+block.  These arguments use header argument syntax rather than standard
 
+function call syntax.  Inside header arguments affect how the code block is
 
+evaluated. For example, @code{[:results output]} will collect the results of
 
+everything printed to @code{STDOUT} during execution of the code block.
 
+@item <end header arguments>
 
+End header arguments are applied to the calling instance and do not affect
 
+evaluation of the named code block.  They affect how the results are
 
+incorporated into the Org-mode buffer and how the call line is exported.  For
 
+example, @code{:results html} will insert the results of the call line
 
+evaluation in the Org buffer, wrapped in a @code{BEGIN_HTML:} block.
 
+
 
+For more examples of passing header arguments to @code{#+CALL:} lines see
 
 @ref{Header arguments in function calls}.
 
 @ref{Header arguments in function calls}.
 
 @end table
 
 @end table
 
 
 
@@ -11909,15 +11909,19 @@ For more examples of passing header arguments to @code{#+call:} lines see
 
 @cindex source code, library
 
 @cindex source code, library
 
 @cindex code block, library
 
 @cindex code block, library
 
 
 
-The ``Library of Babel'' is a library of code blocks
 
-that can be called from any Org-mode file.  The library is housed in an
 
-Org-mode file located in the @samp{contrib} directory of Org-mode.
 
-Org-mode users can deposit functions they believe to be generally
 
-useful in the library.
 
+The ``Library of Babel'' consists of code blocks that can be called from any
 
+Org-mode file.  Code blocks defined in the ``Library of Babel'' can be called
 
+remotely as if they were in the current Org-mode buffer (see @ref{Evaluating
 
+code blocks} for information on the syntax of remote code block evaluation).
 
+
 
+
 
+The central repository of code blocks in the ``Library of Babel'' is housed
 
+in an Org-mode file located in the @samp{contrib} directory of Org-mode.
 
+
 
+Users can add code blocks they believe to be generally useful to their
 
+``Library of Babel.''  The code blocks can be stored in any Org-mode file and
 
+then loaded into the library with @code{org-babel-lob-ingest}.
 
 
 
-Code blocks defined in the ``Library of Babel'' can be called remotely as if
 
-they were in the current Org-mode buffer (see @ref{Evaluating code blocks}
 
-for information on the syntax of remote code block evaluation).
 
 
 
 @kindex C-c C-v i
 
 @kindex C-c C-v i
 
 Code blocks located in any Org-mode file can be loaded into the ``Library of
 
 Code blocks located in any Org-mode file can be loaded into the ``Library of
 
@@ -12111,7 +12115,7 @@ in Org-mode documents.
 
 
 
 The most common way to assign values to header arguments is at the
 
 The most common way to assign values to header arguments is at the
 
 code block level.  This can be done by listing a sequence of header
 
 code block level.  This can be done by listing a sequence of header
 
-arguments and their values as part of the @code{#+begin_src} line.
 
+arguments and their values as part of the @code{#+BEGIN_SRC} line.
 
 Properties set in this way override both the values of
 
 Properties set in this way override both the values of
 
 @code{org-babel-default-header-args} and header arguments specified as
 
 @code{org-babel-default-header-args} and header arguments specified as
 
 properties.  In the following example, the @code{:results} header argument
 
 properties.  In the following example, the @code{:results} header argument
 
@@ -12121,28 +12125,30 @@ inserted in the buffer, and the @code{:exports} header argument is set to
 
 preserved on export to HTML or LaTeX.
 
 preserved on export to HTML or LaTeX.
 
 
 
 @example
 
 @example
 
-#+source: factorial
 
-#+begin_src haskell :results silent :exports code :var n=0
 
+#+NAME: factorial
 
+#+BEGIN_SRC haskell :results silent :exports code :var n=0
 
 fac 0 = 1
 
 fac 0 = 1
 
 fac n = n * fac (n-1)
 
 fac n = n * fac (n-1)
 
-#+end_src
 
+#+END_SRC
 
 @end example
 
 @end example
 
-Similarly, it is possible to set header arguments for inline code blocks:
 
+Similarly, it is possible to set header arguments for inline code blocks
 
 
 
 @example
 
 @example
 
 src_haskell[:exports both]@{fac 5@}
 
 src_haskell[:exports both]@{fac 5@}
 
 @end example
 
 @end example
 
 
 
-Code block header arguments can span multiple lines using =#+header:= or
 
-=#+headers:= lines preceding a code block or nested in between the name and
 
-body of a named code block.
 
+Code block header arguments can span multiple lines using @code{#+HEADER:} or
 
+@code{#+HEADERS:} lines preceding a code block or nested between the
 
+@code{#+NAME:} line and the @code{#+BEGIN_SRC} line of a named code block.
 
+@cindex #+HEADER:
 
+@cindex #+HEADERS:
 
 
 
 Multi-line header arguments on an un-named code block:
 
 Multi-line header arguments on an un-named code block:
 
 @example
 
 @example
 
- #+headers: :var data1=1
 
- #+begin_src emacs-lisp :var data2=2
 
+ #+HEADERS: :var data1=1
 
+ #+BEGIN_SRC emacs-lisp :var data2=2
 
    (message "data1:%S, data2:%S" data1 data2)
 
    (message "data1:%S, data2:%S" data1 data2)
 
- #+end_src
 
+ #+END_SRC
 
 
 
  #+results:
 
  #+results:
 
  : data1:1, data2:2
 
  : data1:1, data2:2
 
@@ -12150,11 +12156,11 @@ Multi-line header arguments on an un-named code block:
 
 
 
 Multi-line header arguments on a named code block:
 
 Multi-line header arguments on a named code block:
 
 @example
 
 @example
 
-   #+source: named-block
 
-   #+header: :var data=2
 
-   #+begin_src emacs-lisp
 
+   #+NAME: named-block
 
+   #+HEADER: :var data=2
 
+   #+BEGIN_SRC emacs-lisp
 
      (message "data:%S" data)
 
      (message "data:%S" data)
 
-   #+end_src
 
+   #+END_SRC
 
 
 
    #+results: named-block
 
    #+results: named-block
 
    : data:2
 
    : data:2
 
@@ -12165,20 +12171,20 @@ Multi-line header arguments on a named code block:
 
 @subsubheading Header arguments in function calls
 
 @subsubheading Header arguments in function calls
 
 
 
 At the most specific level, header arguments for ``Library of Babel'' or
 
 At the most specific level, header arguments for ``Library of Babel'' or
 
-function call lines can be set as shown in the two examples below.  For more
 
-information on the structure of @code{#+call:} lines see @ref{Evaluating code
 
+@code{#+CALL:} lines can be set as shown in the two examples below.  For more
 
+information on the structure of @code{#+CALL:} lines see @ref{Evaluating code
 
 blocks}.
 
 blocks}.
 
 
 
 The following will apply the @code{:exports results} header argument to the
 
 The following will apply the @code{:exports results} header argument to the
 
-evaluation of the @code{#+call:} line.
 
+evaluation of the @code{#+CALL:} line.
 
 @example
 
 @example
 
-#+call: factorial(n=5) :exports results
 
+#+CALL: factorial(n=5) :exports results
 
 @end example
 
 @end example
 
 
 
 The following will apply the @code{:session special} header argument to the
 
 The following will apply the @code{:session special} header argument to the
 
 evaluation of the @code{factorial} code block.
 
 evaluation of the @code{factorial} code block.
 
 @example
 
 @example
 
-#+call: factorial[:session special](n=5)
 
+#+CALL: factorial[:session special](n=5)
 
 @end example
 
 @end example
 
 
 
 @node Specific header arguments,  , Using header arguments, Header arguments
 
 @node Specific header arguments,  , Using header arguments, Header arguments
 
@@ -12223,14 +12229,18 @@ Additional header arguments are defined on a language-specific basis, see
 
 The @code{:var} header argument is used to pass arguments to code blocks.
 
 The @code{:var} header argument is used to pass arguments to code blocks.
 
 The specifics of how arguments are included in a code block vary by language;
 
 The specifics of how arguments are included in a code block vary by language;
 
 these are addressed in the language-specific documentation.  However, the
 
 these are addressed in the language-specific documentation.  However, the
 
-syntax used to specify arguments is the same across all languages.  The
 
-values passed to arguments can be literal values, values from org-mode tables
 
-and literal example blocks, the results of other code blocks, or Emacs Lisp
 
-code---see the ``Emacs Lisp evaluation of variables'' heading below.  In
 
-every case, variables require a default value when they are declared.
 
+syntax used to specify arguments is the same across all languages.  In every
 
+case, variables require a default value when they are declared.
 
 
 
-These values can be indexed in a manner similar to arrays---see the
 
-``indexable variable values'' heading below.
 
+The values passed to arguments can either be literal values, references, or
 
+Emacs Lisp code (see @ref{Emacs Lisp evaluation of variables}). References
 
+include anything in the Org-mode file that takes a @code{#+NAME:},
 
+@code{#+TBLNAME:}, or @code{#+RESULTS:} line.  This includes tables, lists,
 
+@code{#+BEGIN_EXAMPLE} blocks, other code blocks, and the results of other
 
+code blocks.
 
+
 
+Argument values can be indexed in a manner similar to arrays (see
 
+@ref{Indexable variable values}).
 
 
 
 The following syntax is used to pass arguments to code blocks using the
 
 The following syntax is used to pass arguments to code blocks using the
 
 @code{:var} header argument.
 
 @code{:var} header argument.
 
@@ -12241,74 +12251,134 @@ The following syntax is used to pass arguments to code blocks using the
 
 
 
 where @code{assign} can take one of the following forms
 
 where @code{assign} can take one of the following forms
 
 
 
-@itemize @bullet
 
+@table @asis
 
 @item literal value
 
 @item literal value
 
-either a string @code{"string"} or a number @code{9}.
 
+either a string @samp{"string"} or a number @samp{9}.
 
 @item reference
 
 @item reference
 
-a table name:
 
+tables, lists, literal examples, other code blocks, and results blocks can
 
+all be passed by reference
 
+@table @asis
 
+@item table
 
 
 
 @example
 
 @example
 
-#+tblname: example-table
 
+#+TBLNAME: example-table
 
 | 1 |
 
 | 1 |
 
 | 2 |
 
 | 2 |
 
 | 3 |
 
 | 3 |
 
 | 4 |
 
 | 4 |
 
 
 
-#+source: table-length
 
-#+begin_src emacs-lisp :var table=example-table
 
+#+NAME: table-length
 
+#+BEGIN_SRC emacs-lisp :var table=example-table
 
 (length table)
 
 (length table)
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results: table-length
 
 #+results: table-length
 
 : 4
 
 : 4
 
 @end example
 
 @end example
 
 
 
-a code block name, as assigned by @code{#+srcname:}, followed by
 
+@item list
 
+a named, simple list.  Nesting is not carried through to the source code
 
+block.
 
+ 
+@example
 
+#+NAME: example-list
 
+  - simple
 
+    - not
 
+    - nested
 
+  - lists
 
+
 
+#+BEGIN_SRC emacs-lisp :var x=example-list
 
+  (print x)
 
+#+END_SRC
 
+
 
+#+RESULTS:
 
+| simple | lists |
 
+@end example
 
+
 
+@item code block
 
+a code block name, as assigned by @code{#+NAME:}, followed by
 
 parentheses:
 
 parentheses:
 
 
 
 @example
 
 @example
 
-#+begin_src emacs-lisp :var length=table-length()
 
+#+BEGIN_SRC emacs-lisp :var length=table-length()
 
 (* 2 length)
 
 (* 2 length)
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results:
 
 #+results:
 
 : 8
 
 : 8
 
 @end example
 
 @end example
 
 
 
-In addition, an argument can be passed to the code block referenced
 
-by @code{:var}.  The argument is passed within the parentheses following the
 
-code block name:
 
+In addition, an argument can be passed to the code block referenced by
 
+@code{:var}.  The argument is passed within the parentheses following the
 
+code block name using standard function call syntax:
 
 
 
 @example
 
 @example
 
-#+source: double
 
-#+begin_src emacs-lisp :var input=8
 
+#+NAME: double
 
+#+BEGIN_SRC emacs-lisp :var input=8
 
 (* 2 input)
 
 (* 2 input)
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results: double
 
 #+results: double
 
 : 16
 
 : 16
 
 
 
-#+source: squared
 
-#+begin_src emacs-lisp :var input=double(input=1)
 
+#+NAME: squared
 
+#+BEGIN_SRC emacs-lisp :var input=double(input=1)
 
 (* input input)
 
 (* input input)
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results: squared
 
 #+results: squared
 
 : 4
 
 : 4
 
 @end example
 
 @end example
 
-@end itemize
 
+
 
+@item literal example
 
+named literal examples are passed intact
 
+
 
+@example
 
+#+NAME: literal-example
 
+#+BEGIN_EXAMPLE
 
+A literal example
 
+on two lines
 
+#+END_EXAMPLE
 
+
 
+#+NAME: read-literal-example
 
+#+BEGIN_SRC emacs-lisp :var x=literal-example
 
+  (concatenate 'string x " for you.")
 
+#+END_SRC
 
+
 
+#+results: read-literal-example
 
+: A literal example
 
+: on two lines for you.
 
+
 
+@end example
 
+
 
+@item results block
 
+
 
+named results blocks are passed intact.  Referring to the results of the last
 
+example 
+
 
+@example
 
+#+BEGIN_SRC emacs-lisp :var x=read-literal-example
 
+  (concatenate 'string x "\nAgain.")
 
+#+END_SRC
 
+
 
+#+results:
 
+: A literal example
 
+: on two lines for you.
 
+: Again.
 
+@end example
 
+@end table
 
 
 
 @subsubheading Alternate argument syntax
 
 @subsubheading Alternate argument syntax
 
 It is also possible to specify arguments in a potentially more natural way
 
 It is also possible to specify arguments in a potentially more natural way
 
-using the @code{#+source:} line of a code block.  As in the following
 
-example arguments can be packed inside of parenthesis, separated by commas,
 
+using the @code{#+NAME:} line of a code block.  As in the following
 
+example, arguments can be packed inside of parenthesis, separated by commas,
 
 following the source name.
 
 following the source name.
 
 
 
 @example
 
 @example
 
-#+source: double(input=0, x=2)
 
-#+begin_src emacs-lisp
 
+#+NAME: double(input=0, x=2)
 
+#+BEGIN_SRC emacs-lisp
 
 (* 2 (+ input x))
 
 (* 2 (+ input x))
 
-#+end_src
 
+#+END_SRC
 
 @end example
 
 @end example
 
 
 
 @subsubheading Indexable variable values
 
 @subsubheading Indexable variable values
 
@@ -12322,15 +12392,15 @@ following example assigns the last cell of the first row the table
 
 @code{example-table} to the variable @code{data}:
 
 @code{example-table} to the variable @code{data}:
 
 
 
 @example
 
 @example
 
-#+results: example-table
 
+#+NAME: example-table
 
 | 1 | a |
 
 | 1 | a |
 
 | 2 | b |
 
 | 2 | b |
 
 | 3 | c |
 
 | 3 | c |
 
 | 4 | d |
 
 | 4 | d |
 
 
 
-#+begin_src emacs-lisp :var data=example-table[0,-1]
 
+#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
 
   data
 
   data
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results:
 
 #+results:
 
 : a
 
 : a
 
@@ -12342,16 +12412,16 @@ example the following assigns the middle three rows of @code{example-table}
 
 to @code{data}.
 
 to @code{data}.
 
 
 
 @example
 
 @example
 
-#+results: example-table
 
+#+NAME: example-table
 
 | 1 | a |
 
 | 1 | a |
 
 | 2 | b |
 
 | 2 | b |
 
 | 3 | c |
 
 | 3 | c |
 
 | 4 | d |
 
 | 4 | d |
 
 | 5 | 3 |
 
 | 5 | 3 |
 
 
 
-#+begin_src emacs-lisp :var data=example-table[1:3]
 
+#+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
 
   data
 
   data
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results:
 
 #+results:
 
 | 2 | b |
 
 | 2 | b |
 
@@ -12365,15 +12435,15 @@ interpreted to mean the entire range and as such are equivalent to
 
 column is referenced.
 
 column is referenced.
 
 
 
 @example
 
 @example
 
-#+results: example-table
 
+#+NAME: example-table
 
 | 1 | a |
 
 | 1 | a |
 
 | 2 | b |
 
 | 2 | b |
 
 | 3 | c |
 
 | 3 | c |
 
 | 4 | d |
 
 | 4 | d |
 
 
 
-#+begin_src emacs-lisp :var data=example-table[,0]
 
+#+BEGIN_SRC emacs-lisp :var data=example-table[,0]
 
   data
 
   data
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results:
 
 #+results:
 
 | 1 | 2 | 3 | 4 |
 
 | 1 | 2 | 3 | 4 |
 
@@ -12384,16 +12454,16 @@ Any number of dimensions can be indexed.  Dimensions are separated from one
 
 another by commas, as shown in the following example.
 
 another by commas, as shown in the following example.
 
 
 
 @example
 
 @example
 
-#+source: 3D
 
-#+begin_src emacs-lisp
 
+#+NAME: 3D
 
+#+BEGIN_SRC emacs-lisp
 
   '(((1  2  3)  (4  5  6)  (7  8  9))
 
   '(((1  2  3)  (4  5  6)  (7  8  9))
 
     ((10 11 12) (13 14 15) (16 17 18))
 
     ((10 11 12) (13 14 15) (16 17 18))
 
     ((19 20 21) (22 23 24) (25 26 27)))
 
     ((19 20 21) (22 23 24) (25 26 27)))
 
-#+end_src
 
+#+END_SRC
 
 
 
-#+begin_src emacs-lisp :var data=3D[1,,1]
 
+#+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
 
   data
 
   data
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results:
 
 #+results:
 
 | 11 | 14 | 17 |
 
 | 11 | 14 | 17 |
 
@@ -12402,31 +12472,31 @@ another by commas, as shown in the following example.
 
 @subsubheading Emacs Lisp evaluation of variables
 
 @subsubheading Emacs Lisp evaluation of variables
 
 
 
 Emacs lisp code can be used to initialize variable values.  When a variable
 
 Emacs lisp code can be used to initialize variable values.  When a variable
 
-value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be evaluated as
 
-Emacs Lisp and the result of the evaluation will be assigned as the variable
 
-value.  The following example demonstrates use of this evaluation to reliably
 
-pass the file-name of the org-mode buffer to a code block---note that
 
-evaluation of header arguments is guaranteed to take place in the original
 
-org-mode file, while there is no such guarantee for evaluation of the code
 
-block body.
 
+value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be
 
+evaluated as Emacs Lisp and the result of the evaluation will be assigned as
 
+the variable value.  The following example demonstrates use of this
 
+evaluation to reliably pass the file-name of the org-mode buffer to a code
 
+block---note that evaluation of header arguments is guaranteed to take place
 
+in the original Org-mode file, while there is no such guarantee for
 
+evaluation of the code block body.
 
 
 
 @example
 
 @example
 
-#+begin_src sh :var filename=(buffer-file-name) :exports both
 
+#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
 
   wc -w $filename
 
   wc -w $filename
 
-#+end_src
 
+#+END_SRC
 
 @end example
 
 @end example
 
 
 
 Note that values read from tables and lists will not be evaluated as
 
 Note that values read from tables and lists will not be evaluated as
 
 Emacs Lisp, as shown in the following example.
 
 Emacs Lisp, as shown in the following example.
 
 
 
 @example
 
 @example
 
-#+results: table
 
+#+NAME: table
 
 | (a b c) |
 
 | (a b c) |
 
 
 
-#+headers: :var data=table[0,0]
 
-#+begin_src perl
 
+#+HEADERS: :var data=table[0,0]
 
+#+BEGIN_SRC perl
 
   $data
 
   $data
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results:
 
 #+results:
 
 : (a b c)
 
 : (a b c)
 
@@ -12569,9 +12639,9 @@ In other words, if you want your plot to go into a folder called @file{Work}
 
 in your home directory, you could use
 
 in your home directory, you could use
 
 
 
 @example
 
 @example
 
-#+begin_src R :file myplot.png :dir ~/Work
 
+#+BEGIN_SRC R :file myplot.png :dir ~/Work
 
 matplot(matrix(rnorm(100), 10), type="l")
 
 matplot(matrix(rnorm(100), 10), type="l")
 
-#+end_src
 
+#+END_SRC
 
 @end example
 
 @end example
 
 
 
 @subsubheading Remote execution
 
 @subsubheading Remote execution
 
@@ -12579,9 +12649,9 @@ A directory on a remote machine can be specified using tramp file syntax, in
 
 which case the code will be evaluated on the remote machine.  An example is
 
 which case the code will be evaluated on the remote machine.  An example is
 
 
 
 @example
 
 @example
 
-#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu:
 
+#+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu:
 
 plot(1:10, main=system("hostname", intern=TRUE))
 
 plot(1:10, main=system("hostname", intern=TRUE))
 
-#+end_src
 
+#+END_SRC
 
 @end example
 
 @end example
 
 
 
 Text results will be returned to the local Org-mode buffer as usual, and file
 
 Text results will be returned to the local Org-mode buffer as usual, and file
 
@@ -12612,7 +12682,7 @@ currently made to alter the directory associated with an existing session.
 
 @code{:dir} should typically not be used to create files during export with
 
 @code{:dir} should typically not be used to create files during export with
 
 @code{:exports results} or @code{:exports both}.  The reason is that, in order
 
 @code{:exports results} or @code{:exports both}.  The reason is that, in order
 
 to retain portability of exported material between machines, during export
 
 to retain portability of exported material between machines, during export
 
-links inserted into the buffer will *not* be expanded against @code{default
 
+links inserted into the buffer will @emph{not} be expanded against @code{default
 
 directory}.  Therefore, if @code{default-directory} is altered using
 
 directory}.  Therefore, if @code{default-directory} is altered using
 
 @code{:dir}, it is probable that the file will be created in a location to
 
 @code{:dir}, it is probable that the file will be created in a location to
 
 which the link does not point.
 
 which the link does not point.
 
@@ -12786,33 +12856,33 @@ following Org-mode file, the bodies of code blocks will be concatenated into
 
 the resulting pure code file.
 
 the resulting pure code file.
 
 
 
 @example
 
 @example
 
- #+begin_src sh :tangle yes :noweb yes :shebang #!/bin/sh
 
+ #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
 
    <<fullest-disk>>
 
    <<fullest-disk>>
 
- #+end_src
 
+ #+END_SRC
 
  * the mount point of the fullest disk
 
  * the mount point of the fullest disk
 
    :PROPERTIES:
 
    :PROPERTIES:
 
    :noweb-ref: fullest-disk
 
    :noweb-ref: fullest-disk
 
    :END:
 
    :END:
 
 
 
  ** query all mounted disks
 
  ** query all mounted disks
 
- #+begin_src sh
 
+ #+BEGIN_SRC sh
 
    df \
 
    df \
 
- #+end_src
 
+ #+END_SRC
 
 
 
  ** strip the header row
 
  ** strip the header row
 
- #+begin_src sh
 
+ #+BEGIN_SRC sh
 
    |sed '1d' \
 
    |sed '1d' \
 
- #+end_src
 
+ #+END_SRC
 
 
 
  ** sort by the percent full
 
  ** sort by the percent full
 
- #+begin_src sh
 
+ #+BEGIN_SRC sh
 
    |awk '@{print $5 " " $6@}'|sort -n |tail -1 \
 
    |awk '@{print $5 " " $6@}'|sort -n |tail -1 \
 
- #+end_src
 
+ #+END_SRC
 
 
 
  ** extract the mount point
 
  ** extract the mount point
 
- #+begin_src sh
 
+ #+BEGIN_SRC sh
 
    |awk '@{print $2@}'
 
    |awk '@{print $2@}'
 
- #+end_src
 
+ #+END_SRC
 
 @end example
 
 @end example
 
 
 
 @node cache, sep, noweb-ref, Specific header arguments
 
 @node cache, sep, noweb-ref, Specific header arguments
 
@@ -12842,18 +12912,18 @@ invalidated and the code block is re-run.  In the following example,
 
 changed since it was last run.
 
 changed since it was last run.
 
 
 
 @example
 
 @example
 
- #+srcname: random
 
- #+begin_src R :cache yes
 
+ #+NAME: random
 
+ #+BEGIN_SRC R :cache yes
 
  runif(1)
 
  runif(1)
 
- #+end_src
 
+ #+END_SRC
 
 
 
  #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random
 
  #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random
 
  0.4659510825295
 
  0.4659510825295
 
 
 
- #+srcname: caller
 
- #+begin_src emacs-lisp :var x=random :cache yes
 
+ #+NAME: caller
 
+ #+BEGIN_SRC emacs-lisp :var x=random :cache yes
 
  x
 
  x
 
- #+end_src
 
+ #+END_SRC
 
 
 
  #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
 
  #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
 
  0.254227238707244
 
  0.254227238707244
 
@@ -12887,17 +12957,17 @@ variable and raises an error.  Setting @code{:hlines no} or relying on the
 
 default value yields the following results.
 
 default value yields the following results.
 
 
 
 @example
 
 @example
 
-#+tblname: many-cols
 
+#+TBLNAME: many-cols
 
 | a | b | c |
 
 | a | b | c |
 
 |---+---+---|
 
 |---+---+---|
 
 | d | e | f |
 
 | d | e | f |
 
 |---+---+---|
 
 |---+---+---|
 
 | g | h | i |
 
 | g | h | i |
 
 
 
-#+source: echo-table
 
-#+begin_src python :var tab=many-cols
 
+#+NAME: echo-table
 
+#+BEGIN_SRC python :var tab=many-cols
 
   return tab
 
   return tab
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results: echo-table
 
 #+results: echo-table
 
 | a | b | c |
 
 | a | b | c |
 
@@ -12909,17 +12979,17 @@ default value yields the following results.
 
 Leaves hlines in the table.  Setting @code{:hlines yes} has this effect.
 
 Leaves hlines in the table.  Setting @code{:hlines yes} has this effect.
 
 
 
 @example
 
 @example
 
-#+tblname: many-cols
 
+#+TBLNAME: many-cols
 
 | a | b | c |
 
 | a | b | c |
 
 |---+---+---|
 
 |---+---+---|
 
 | d | e | f |
 
 | d | e | f |
 
 |---+---+---|
 
 |---+---+---|
 
 | g | h | i |
 
 | g | h | i |
 
 
 
-#+source: echo-table
 
-#+begin_src python :var tab=many-cols :hlines yes
 
+#+NAME: echo-table
 
+#+BEGIN_SRC python :var tab=many-cols :hlines yes
 
   return tab
 
   return tab
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results: echo-table
 
 #+results: echo-table
 
 | a | b | c |
 
 | a | b | c |
 
@@ -12944,16 +13014,16 @@ names will be removed from the table before
 
 processing, then reapplied to the results.
 
 processing, then reapplied to the results.
 
 
 
 @example
 
 @example
 
-#+tblname: less-cols
 
+#+TBLNAME: less-cols
 
 | a |
 
 | a |
 
 |---|
 
 |---|
 
 | b |
 
 | b |
 
 | c |
 
 | c |
 
 
 
-#+srcname: echo-table-again
 
-#+begin_src python :var tab=less-cols
 
+#+NAME: echo-table-again
 
+#+BEGIN_SRC python :var tab=less-cols
 
   return [[val + '*' for val in row] for row in tab]
 
   return [[val + '*' for val in row] for row in tab]
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results: echo-table-again
 
 #+results: echo-table-again
 
 | a  |
 
 | a  |
 
@@ -12989,14 +13059,14 @@ The first column of the table is removed from the table before processing,
 
 and is then reapplied to the results.
 
 and is then reapplied to the results.
 
 
 
 @example
 
 @example
 
-#+tblname: with-rownames
 
+#+TBLNAME: with-rownames
 
 | one | 1 | 2 | 3 | 4 |  5 |
 
 | one | 1 | 2 | 3 | 4 |  5 |
 
 | two | 6 | 7 | 8 | 9 | 10 |
 
 | two | 6 | 7 | 8 | 9 | 10 |
 
 
 
-#+srcname: echo-table-once-again
 
-#+begin_src python :var tab=with-rownames :rownames yes
 
+#+NAME: echo-table-once-again
 
+#+BEGIN_SRC python :var tab=with-rownames :rownames yes
 
   return [[val + 10 for val in row] for row in tab]
 
   return [[val + 10 for val in row] for row in tab]
 
-#+end_src
 
+#+END_SRC
 
 
 
 #+results: echo-table-once-again
 
 #+results: echo-table-once-again
 
 | one | 11 | 12 | 13 | 14 | 15 |
 
 | one | 11 | 12 | 13 | 14 | 15 |
 
@@ -13093,26 +13163,26 @@ were passed to a non-interactive interpreter running as an external
 
 process.  For example, compare the following two blocks:
 
 process.  For example, compare the following two blocks:
 
 
 
 @example
 
 @example
 
-#+begin_src python :results output
 
+#+BEGIN_SRC python :results output
 
  print "hello"
 
  print "hello"
 
  2
 
  2
 
  print "bye"
 
  print "bye"
 
-#+end_src
 
+#+END_SRC
 
 
 
-#+resname:
 
+#+results:
 
 : hello
 
 : hello
 
 : bye
 
 : bye
 
 @end example
 
 @end example
 
 
 
 In non-session mode, the `2' is not printed and does not appear.
 
 In non-session mode, the `2' is not printed and does not appear.
 
 @example
 
 @example
 
-#+begin_src python :results output :session
 
+#+BEGIN_SRC python :results output :session
 
  print "hello"
 
  print "hello"
 
  2
 
  2
 
  print "bye"
 
  print "bye"
 
-#+end_src
 
+#+END_SRC
 
 
 
-#+resname:
 
+#+results:
 
 : hello
 
 : hello
 
 : 2
 
 : 2
 
 : bye
 
 : bye