ホーム エクスプローラ ヘルプ
サインイン
swflint
/
org-mode-mirror
1
0
フォーク 0
ファイル 課題 0 プルリクエスト 0 Wiki
ソースを参照

Tom's documentation updates for the new code block syntax

Eric Schulte 13 年 前
親
1ed12cac1a
コミット
a3f781be12
1 ファイル変更、275 行追加、205 行削除
分割表示 差分情報を表示
  1. 275 205
      doc/org.texi

+ 275 - 205
doc/org.texi
ファイルの表示 

@@ -11651,19 +11651,26 @@ The following sections describe Org-mode's code block handling facilities.
 
 @section Structure of code blocks
 
 @cindex 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
 
-#+srcname: <name>
 
-#+begin_src <language> <switches> <header arguments>
 
+#+NAME: <name>
 
+#+BEGIN_SRC <language> <switches> <header arguments>
 
   <body>
 
-#+end_src
 
+#+END_SRC
 
 @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
 
 src_<language>@{<body>@}
 
@@ -11676,26 +11683,30 @@ src_<language>[<header arguments>]@{<body>@}
 
 @end example
 
 
 @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.
 
+@cindex #+NAME
 
 @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>
 
-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})
 
+@cindex source code, switches
 
 @item <header arguments>
 
 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
 
 basis using properties.
 
+@item source code, header arguments
 
 @item <body>
 
-The source code.
 
+Source code in the specified language.
 
 @end table
 
 
 @comment  node-name,  next,  previous,  up
 
@@ -11744,12 +11755,12 @@ variable @code{org-src-fontify-natively}.
 
 @cindex code block, 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
 
 behavior:
 
@@ -11827,14 +11838,15 @@ of tangled code files.
 
 @cindex source code, evaluating
 
 
 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
 
 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
 
 @code{org-babel-execute-src-block} function to evaluate the block and insert
 
 its results into the Org-mode buffer.
 
+@cindex #+CALL
 
 
 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
 
-#+call: <name>(<arguments>)
 
-#+call: <name>[<header args>](<arguments>) <header args>
 
+#+CALL: <name>(<arguments>)
 
+#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
 
 @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
 
-...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
 
 
 @table @code
 
 @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>
 
 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}.
 
 @end table
 
 
@@ -11909,15 +11909,19 @@ For more examples of passing header arguments to @code{#+call:} lines see
 
 @cindex source code, 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
 
 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
 
 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
 
 @code{org-babel-default-header-args} and header arguments specified as
 
 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.
 
 
 @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 n = n * fac (n-1)
 
-#+end_src
 
+#+END_SRC
 
 @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
 
 src_haskell[:exports both]@{fac 5@}
 
 @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:
 
 @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)
 
- #+end_src
 
+ #+END_SRC
 
 
  #+results:
 
  : 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:
 
 @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)
 
-   #+end_src
 
+   #+END_SRC
 
 
    #+results: named-block
 
    : data:2
 
@@ -12165,20 +12171,20 @@ Multi-line header arguments on a named code block:
 
 @subsubheading Header arguments in function calls
 
 
 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}.
 
 
 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
 
-#+call: factorial(n=5) :exports results
 
+#+CALL: factorial(n=5) :exports results
 
 @end example
 
 
 The following will apply the @code{:session special} header argument to the
 
 evaluation of the @code{factorial} code block.
 
 @example
 
-#+call: factorial[:session special](n=5)
 
+#+CALL: factorial[:session special](n=5)
 
 @end example
 
 
 @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 specifics of how arguments are included in a code block vary by language;
 
 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
 
 @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
 
 
-@itemize @bullet
 
+@table @asis
 
 @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
 
-a table name:
 
+tables, lists, literal examples, other code blocks, and results blocks can
 
+all be passed by reference
 
+@table @asis
 
+@item table
 
 
 @example
 
-#+tblname: example-table
 
+#+TBLNAME: example-table
 
 | 1 |
 
 | 2 |
 
 | 3 |
 
 | 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)
 
-#+end_src
 
+#+END_SRC
 
 
 #+results: table-length
 
 : 4
 
 @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:
 
 
 @example
 
-#+begin_src emacs-lisp :var length=table-length()
 
+#+BEGIN_SRC emacs-lisp :var length=table-length()
 
 (* 2 length)
 
-#+end_src
 
+#+END_SRC
 
 
 #+results:
 
 : 8
 
 @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
 
-#+source: double
 
-#+begin_src emacs-lisp :var input=8
 
+#+NAME: double
 
+#+BEGIN_SRC emacs-lisp :var input=8
 
 (* 2 input)
 
-#+end_src
 
+#+END_SRC
 
 
 #+results: double
 
 : 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)
 
-#+end_src
 
+#+END_SRC
 
 
 #+results: squared
 
 : 4
 
 @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
 
 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.
 
 
 @example
 
-#+source: double(input=0, x=2)
 
-#+begin_src emacs-lisp
 
+#+NAME: double(input=0, x=2)
 
+#+BEGIN_SRC emacs-lisp
 
 (* 2 (+ input x))
 
-#+end_src
 
+#+END_SRC
 
 @end example
 
 
 @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}:
 
 
 @example
 
-#+results: example-table
 
+#+NAME: example-table
 
 | 1 | a |
 
 | 2 | b |
 
 | 3 | c |
 
 | 4 | d |
 
 
-#+begin_src emacs-lisp :var data=example-table[0,-1]
 
+#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
 
   data
 
-#+end_src
 
+#+END_SRC
 
 
 #+results:
 
 : a
 
@@ -12342,16 +12412,16 @@ example the following assigns the middle three rows of @code{example-table}
 
 to @code{data}.
 
 
 @example
 
-#+results: example-table
 
+#+NAME: example-table
 
 | 1 | a |
 
 | 2 | b |
 
 | 3 | c |
 
 | 4 | d |
 
 | 5 | 3 |
 
 
-#+begin_src emacs-lisp :var data=example-table[1:3]
 
+#+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
 
   data
 
-#+end_src
 
+#+END_SRC
 
 
 #+results:
 
 | 2 | b |
 
@@ -12365,15 +12435,15 @@ interpreted to mean the entire range and as such are equivalent to
 
 column is referenced.
 
 
 @example
 
-#+results: example-table
 
+#+NAME: example-table
 
 | 1 | a |
 
 | 2 | b |
 
 | 3 | c |
 
 | 4 | d |
 
 
-#+begin_src emacs-lisp :var data=example-table[,0]
 
+#+BEGIN_SRC emacs-lisp :var data=example-table[,0]
 
   data
 
-#+end_src
 
+#+END_SRC
 
 
 #+results:
 
 | 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.
 
 
 @example
 
-#+source: 3D
 
-#+begin_src emacs-lisp
 
+#+NAME: 3D
 
+#+BEGIN_SRC emacs-lisp
 
   '(((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)))
 
-#+end_src
 
+#+END_SRC
 
 
-#+begin_src emacs-lisp :var data=3D[1,,1]
 
+#+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
 
   data
 
-#+end_src
 
+#+END_SRC
 
 
 #+results:
 
 | 11 | 14 | 17 |
 
@@ -12402,31 +12472,31 @@ another by commas, as shown in the following example.
 
 @subsubheading Emacs Lisp evaluation of variables
 
 
 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
 
-#+begin_src sh :var filename=(buffer-file-name) :exports both
 
+#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
 
   wc -w $filename
 
-#+end_src
 
+#+END_SRC
 
 @end example
 
 
 Note that values read from tables and lists will not be evaluated as
 
 Emacs Lisp, as shown in the following example.
 
 
 @example
 
-#+results: table
 
+#+NAME: table
 
 | (a b c) |
 
 
-#+headers: :var data=table[0,0]
 
-#+begin_src perl
 
+#+HEADERS: :var data=table[0,0]
 
+#+BEGIN_SRC perl
 
   $data
 
-#+end_src
 
+#+END_SRC
 
 
 #+results:
 
 : (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
 
 
 @example
 
-#+begin_src R :file myplot.png :dir ~/Work
 
+#+BEGIN_SRC R :file myplot.png :dir ~/Work
 
 matplot(matrix(rnorm(100), 10), type="l")
 
-#+end_src
 
+#+END_SRC
 
 @end example
 
 
 @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
 
 
 @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))
 
-#+end_src
 
+#+END_SRC
 
 @end example
 
 
 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{:exports results} or @code{:exports both}.  The reason is that, in order
 
 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
 
 @code{:dir}, it is probable that the file will be created in a location to
 
 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.
 
 
 @example
 
- #+begin_src sh :tangle yes :noweb yes :shebang #!/bin/sh
 
+ #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
 
    <<fullest-disk>>
 
- #+end_src
 
+ #+END_SRC
 
  * the mount point of the fullest disk
 
    :PROPERTIES:
 
    :noweb-ref: fullest-disk
 
    :END:
 
 
  ** query all mounted disks
 
- #+begin_src sh
 
+ #+BEGIN_SRC sh
 
    df \
 
- #+end_src
 
+ #+END_SRC
 
 
  ** strip the header row
 
- #+begin_src sh
 
+ #+BEGIN_SRC sh
 
    |sed '1d' \
 
- #+end_src
 
+ #+END_SRC
 
 
  ** sort by the percent full
 
- #+begin_src sh
 
+ #+BEGIN_SRC sh
 
    |awk '@{print $5 " " $6@}'|sort -n |tail -1 \
 
- #+end_src
 
+ #+END_SRC
 
 
  ** extract the mount point
 
- #+begin_src sh
 
+ #+BEGIN_SRC sh
 
    |awk '@{print $2@}'
 
- #+end_src
 
+ #+END_SRC
 
 @end example
 
 
 @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.
 
 
 @example
 
- #+srcname: random
 
- #+begin_src R :cache yes
 
+ #+NAME: random
 
+ #+BEGIN_SRC R :cache yes
 
  runif(1)
 
- #+end_src
 
+ #+END_SRC
 
 
  #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random
 
  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
 
- #+end_src
 
+ #+END_SRC
 
 
  #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
 
  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.
 
 
 @example
 
-#+tblname: many-cols
 
+#+TBLNAME: many-cols
 
 | a | b | c |
 
 |---+---+---|
 
 | d | e | f |
 
 |---+---+---|
 
 | 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
 
-#+end_src
 
+#+END_SRC
 
 
 #+results: echo-table
 
 | 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.
 
 
 @example
 
-#+tblname: many-cols
 
+#+TBLNAME: many-cols
 
 | a | b | c |
 
 |---+---+---|
 
 | d | e | f |
 
 |---+---+---|
 
 | 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
 
-#+end_src
 
+#+END_SRC
 
 
 #+results: echo-table
 
 | a | b | c |
 
@@ -12944,16 +13014,16 @@ names will be removed from the table before
 
 processing, then reapplied to the results.
 
 
 @example
 
-#+tblname: less-cols
 
+#+TBLNAME: less-cols
 
 | a |
 
 |---|
 
 | b |
 
 | 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]
 
-#+end_src
 
+#+END_SRC
 
 
 #+results: echo-table-again
 
 | 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.
 
 
 @example
 
-#+tblname: with-rownames
 
+#+TBLNAME: with-rownames
 
 | one | 1 | 2 | 3 | 4 |  5 |
 
 | 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]
 
-#+end_src
 
+#+END_SRC
 
 
 #+results: echo-table-once-again
 
 | 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:
 
 
 @example
 
-#+begin_src python :results output
 
+#+BEGIN_SRC python :results output
 
  print "hello"
 
  2
 
  print "bye"
 
-#+end_src
 
+#+END_SRC
 
 
-#+resname:
 
+#+results:
 
 : hello
 
 : bye
 
 @end example
 
 
 In non-session mode, the `2' is not printed and does not appear.
 
 @example
 
-#+begin_src python :results output :session
 
+#+BEGIN_SRC python :results output :session
 
  print "hello"
 
  2
 
  print "bye"
 
-#+end_src
 
+#+END_SRC
 
 
-#+resname:
 
+#+results:
 
 : hello
 
 : 2
 
 : bye