First pass through babel documentation (on airplane)

doc/org.texi

@@ -11050,13 +11050,13 @@ Header arguments can be placed after the function invocation.  See
 
 @node Library of Babel, Languages, Evaluating code blocks, Working With Source Code
 @section Library of Babel
-The ``Library of Babel'' is two things.  First, it is a library of code blocks
-that can be called from any Org-mode file, and second it is an actual
-Org-mode file located in the @samp{contrib} directory of Org-mode in which
-Org-mode users may deposit functions they believe to be generally
-useful.
+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.
 
-Code blocks defined in the``Library of Babel'' can be called remotely as if
+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).
 
@@ -11066,9 +11066,7 @@ l}.
 
 @node Languages, Header arguments, Library of Babel, Working With Source Code
 @section Languages
-Org-babel provides support for the following languages. See the language
-specific documentation and an up to date list of languages is available at
-@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}.
+Code blocks in the following languages are supported.
 
 @c BEGIN RECEIVE ORGTBL org-babel-lang-table
 @multitable @columnfractions 0.583 0.417
@@ -11155,8 +11153,12 @@ The original table from reference.org is below; I'm just using the first column
 
 
 @end ignore
+ See the language specific documentation and an up to date list of languages
+that is available at
+@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}.
 
-To add support for a particular language to your Org-babel installation first
+
+To add support for a particular language to your installation, first
 make sure that the requirements of the language are met, then add a line like
 the following to your Emacs configuration, (replace ``identifier'' with one
 of the language names from the above table).
@@ -11185,10 +11187,10 @@ The values of header arguments can be set in five different ways, each more
 specific (and having higher priority) than the last.
 @menu
 * System-wide header arguments::
-* Language Specific header arguments::
-* Buffer Wide header arguments::
-* header arguments in Org-mode Properties::
-* Source Code Block specific header arguments::
+* Language-specific header arguments::
+* Buffer-wide header arguments::
+* Header arguments in Org-mode properties::
+* Code block specific header arguments::
 @end menu
 
 @node System-wide header arguments, Language Specific header arguments, , Using Header arguments
@@ -11207,7 +11209,7 @@ System-wide values of header arguments can be specified by customizing the
 
 
   Documentation:
-  Default arguments to use when evaluating a source block.
+  Default arguments to use when evaluating a code block.
 @end example
 
 For example, the following example could be used to set the default value of
@@ -11222,14 +11224,14 @@ blocks.
 @end example
 
 @node Language Specific header arguments, Buffer Wide header arguments, System-wide header arguments, Using Header arguments
-@subsubheading Language Specific header arguments
-Each language can define it's own set of default header arguments.  See the
+@subsubheading Language-specific header arguments
+Each language can define its own set of default header arguments.  See the
 language-specific documentation available at
 @uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}.
 for information on language-specific header arguments.
 
 @node Buffer Wide header arguments, header arguments in Org-mode Properties, Language Specific header arguments, Using Header arguments
-@subsubheading Buffer Wide header arguments
+@subsubheading Buffer-wide header arguments
 FIXME
 
 @node header arguments in Org-mode Properties, Source Code Block specific header arguments, Buffer Wide header arguments, Using Header arguments
@@ -11244,8 +11246,8 @@ of setting a header argument for all code blocks in a buffer is
 @end example
 
 When properties are used to set default header arguments, they are looked up
-with inheritance, so the value of the =:cache= header argument will default
-to true in all source code blocks in the subtree rooted at the following
+with inheritance, so the value of the @code{:cache} header argument will default
+to @code{yes} in all source code blocks in the subtree rooted at the following
 heading:
 
 @example
@@ -11261,9 +11263,9 @@ Properties defined in this way override the properties set in
 in Org-mode documents.
 
 @node Source Code Block specific header arguments, , header arguments in Org-mode Properties, Using Header arguments
-@subsubheading Source Code Block specific header arguments
+@subsubheading Code block specific header arguments
 
-The most common way to assign values to header arguments is at the source
+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.
 Properties set in this way override both the values of
@@ -11282,14 +11284,13 @@ preserved on export to HTML or LaTeX.
   #+end_src
 @end example
 
-Similarly it is possible to set header arguments for inline code blocks as
-shown,
+Similarly, it is possible to set header arguments for inline code blocks:
 
 @example
 src_haskell[:exports both]@{fac 5@}
 @end example
 
-and for ``Library of Babel'' or function call lines as shown below.
+Header arguments for ``Library of Babel'' or function call lines can be set as shown below:
 
 @example
 #+call: factorial(n=5) :exports results
@@ -11297,8 +11298,7 @@ and for ``Library of Babel'' or function call lines as shown below.
 
 @node Specific Header arguments, , Using Header arguments, Header arguments
 @subsection Specific Header arguments
-Description of every standard (non language-specific) Org-babel header
-argument.
+The following header arguments are defined:
 
 @menu
 * var::
@@ -11319,22 +11319,22 @@ argument.
 @node var, results, , Specific Header arguments
 @subsubsection var
 The @code{:var} header argument is used to pass arguments to
-source code blocks.  The specifics of how arguments are included
-in a source code block are language specific and are
+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 or
+languages.  The values passed to arguments can be
 @itemize @bullet
 @item literal values
 @item values from org-mode tables
 @item the results of other source code blocks
 @end itemize
 
-These values can be indexed in a manner similar to arrays -- see the argument
+These values can be indexed in a manner similar to arrays---see the argument
 ``indexable variable values'' heading below.
 
-The following syntax is used to pass arguments to source code
-blocks using the @code{:var} header argument.
+The following syntax is used to pass arguments to code blocks using the
+@code{:var} header argument.
 
 @example
   :var name=assign
@@ -11376,7 +11376,7 @@ parentheses:
   : 8
 @end example
 
-In addition, an argument can be passed to the source code block referenced
+In addition, an argument can be passed to the code block referenced
 by @code{:var}.  The argument is passed within the parentheses following the
 source code block name:
 
@@ -11399,16 +11399,16 @@ source code block name:
 @end example
 @end itemize
 
-@subsubheading alternate argument syntax
+@subsubheading Alternate argument syntax
 It is also possible to specify arguments in a potentially more natural way
 using the @code{#+source:} line of a source code block.  As in the following
-example arguments can be packed inside of parenthesis following the source
-name.
+example arguments can be packed inside of parenthesis, separated by commas,
+following the source name.
 
 @example
-  #+source: double(input=0)
+  #+source: double(input=0, x=2)
   #+begin_src emacs-lisp
-    (* 2 input)
+    (* 2 (+ input x))
   #+end_src
 @end example
 
@@ -11421,7 +11421,7 @@ block.  The following example assigns the second and third rows of the table
   :var data=example-table[1:2]
 @end example
 
-Note: ranges are indexed using the =:= operator.
+Note: ranges are indexed using the @code{:} operator.
 
 Note: indices are 0 based.
 
@@ -11432,12 +11432,12 @@ The following example assigns the second column of the first row of
   :var data=example-table[0,1]
 @end example
 
-It is possible to index into the results of source code blocks as well as
+It is possible to index into the results of code blocks as well as
 tables.  Any number of dimensions can be indexed.  Dimensions are separated
 from one another by commas.
 
 For more information on indexing behavior see the documentation for the
-@code{org-babel-ref-index-list} function -- provided below.
+@code{org-babel-ref-index-list} function, provided below.
 
 @example
   org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'.
@@ -11451,16 +11451,11 @@ For more information on indexing behavior see the documentation for the
   which case the entire range is returned.
 @end example
 
-Note: In Emacs, the documentation for any function or variable can be read
-using the @code{describe-function} (M-x describe function) and
-@code{describe-variable} (M-x describe variable) functions, respectively.
-
 @node results, file, var, Specific Header arguments
 @subsubsection results
 
-There are three types of results header argument:
-
-Note: only one option from each type may be supplied per source code block.
+There are three types of results header argument.  Only one option of each
+type may be supplied per code block.
 
 @itemize @bullet
 @item collection
@@ -11468,7 +11463,7 @@ arguments specify how the results should be collected from the source code
 block
 @item type
 header arguments specify what type of result the source code block will
-return -- which has implications for how they will be inserted into the
+return---which has implications for how they will be inserted into the
 Org-mode buffer
 @item handling
 header arguments specify how the results of evaluating the source code block
@@ -11482,14 +11477,14 @@ should be collected from the source code block.
 @itemize @bullet
 @item value
 This is the default.  The result is the value of the last statement in the
-source code block.  This header argument places Org-babel in functional mode.
-Note that in some languages, e.g., python, use of this result type requires
-that a @code{return} statement be included in the body of the source code
-block. E.g., @code{:results value}.
+source code block.  This header argument places the evaluation in functional
+mode.  Note that in some languages, e.g., python, use of this result type
+requires that a @code{return} statement be included in the body of the source
+code block. E.g., @code{:results value}.
 @item output
 The result is the collection of everything printed to STDOUT during the
-execution of the source code block.  This header argument places Org-babel in
-scripting mode.  E.g., @code{:results output}.
+execution of the source code block.  This header argument places the
+evaluation in scripting mode.  E.g., @code{:results output}.
 @end itemize
 
 @subsubheading type
@@ -11501,10 +11496,10 @@ table or scalar depending on their value.
 @itemize @bullet
 @item table, vector
 The results should be interpreted as an Org-mode table.  If a single value is
-returned, Org-babel will convert it into a table with one row and one column.
+returned, it will be converted into a table with one row and one column.
 E.g., @code{:results value table}.
 @item scalar, verbatim
-The results should be interpreted literally -- meaning they will not be
+The results should be interpreted literally---they will not be
 converted into a table.  The results will be inserted into the Org-mode
 buffer as quoted text.  E.g., @code{:results value verbatim}.
 @item file
@@ -11565,17 +11560,16 @@ individual languages for details. In contrast, general purpose languages such
 as python and ruby require that the code explicitly create output
 corresponding to the path indicated by @code{:file}.
 
-While the @code{:file} header argument can be used to specify the path to the
-output file,
 
 @node dir and remote execution, exports, file, Specific Header arguments
 @subsubsection dir and remote execution
-@code{:dir} specifies the /default directory/ during code block execution. If
-it is absent, then the directory associated with the current buffer is
-used. In other words, supplying @code{:dir path} temporarily has the same
-effect as changing the current directory with @key{M-x cd path}, and then not
-supplying @code{:dir}. Under the surface, @code{:dir} simply sets the value
-of the Emacs variable @code{default-directory}.
+While the @code{:file} header argument can be used to specify the path to the
+output file, @code{:dir} specifies the default directory during code block
+execution. If it is absent, then the directory associated with the current
+buffer is used. In other words, supplying @code{:dir path} temporarily has
+the same effect as changing the current directory with @key{M-x cd path}, and
+then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets
+the value of the Emacs variable @code{default-directory}.
 
 When using @code{:dir}, you should supply a relative path for file output
 (e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
@@ -11600,12 +11594,12 @@ which case the code will be evaluated on the remote machine. An example is
 #+end_src
 @end example
 
-Text results will be returned to the local org buffer as normal, and
-file output will be created on the remote machine with relative paths
-interpreted relative to the remote directory. An org link to the
-remote file will be created.
+Text results will be returned to the local Org-mode buffer as usual, and file
+output will be created on the remote machine with relative paths interpreted
+relative to the remote directory. An Org-mode link to the remote file will be
+created.
 
-So in the above example a plot will be created on the remote machine,
+So, in the above example a plot will be created on the remote machine,
 and a link of the following form will be inserted in the org buffer:
 
 @example 
@@ -11615,7 +11609,7 @@ and a link of the following form will be inserted in the org buffer:
 Most of this functionality follows immediately from the fact that @code{:dir}
 sets the value of the Emacs variable @code{default-directory}, thanks to
 tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to
-install tramp separately in order for the above features to work correctly.
+install tramp separately in order for the these features to work correctly.
 
 @subsubheading Further points
 
@@ -11627,11 +11621,11 @@ currently made to alter the directory associated with an existing session.
 @item
 @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 default
-directory. Therefore, if default-directory is altered using @code{:dir}, it
-it probable that the file will be created in a location to which the link
-does not point.
+to retain portability of exported material between machines, during export
+links inserted into the buffer will *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.
 @end itemize
 
 @node exports, tangle, dir and remote execution, Specific Header arguments
@@ -11753,7 +11747,7 @@ changed since the last time it was evaluated, it will not be re-evaluated.
 @node hlines, colnames, cache, Specific Header arguments
 @subsubsection hlines
 Tables are frequently represented with one or more horizontal lines, or
-hlines.  The @code{:hlines} argument to an Org-babel code block accepts the
+hlines.  The @code{:hlines} argument to a code block accepts the
 values @code{yes} or @code{no}, with a default value of @code{no}.
 
 @itemize @bullet
@@ -11814,9 +11808,9 @@ The @code{:colnames} header argument accepts the values @code{yes},
 
 @itemize @bullet
 @item @code{nil}
-If an input table /looks like/ it has column names
+If an input table looks like it has column names
 (because its second row is an hline), then the column
-names will be removed from the table by Org-babel before
+names will be removed from the table before
 processing, then reapplied to the results.
 
 @example
@@ -11857,9 +11851,8 @@ or @code{no}, with a default value of @code{no}.
 No row name pre-processing will take place.
 
 @item @code{yes}
-The first column of the table is removed from the
-table by Org-babel before processing, and is then reapplied
-to the results.
+The first column of the table is removed from the table before processing,
+and is then reapplied to the results.
 
 @example
 #+tblname: with-rownames
@@ -11967,11 +11960,11 @@ familiar Noweb syntax:
 <<code-block-name>>
 @end example
 
-When a source code block is tangled or evaluated, ``noweb'' references are
-expanded depends upon the value of the @code{:noweb} header argument.  If
-@code{:noweb yes}, then a Noweb reference is expanded before evaluation.  If
-@code{:noweb no}, the default, then the reference is not expanded before
-evaluation.
+When a source code block is tangled or evaluated, whether or not ``noweb''
+references are expanded depends upon the value of the @code{:noweb} header
+argument.  If @code{:noweb yes}, then a Noweb reference is expanded before
+evaluation.  If @code{:noweb no}, the default, then the reference is not
+expanded before evaluation.
 
 Note: the default value, @code{:noweb no}, was chosen to ensure that
 Org-babel does not break correct code in a language, such as Ruby, where
@@ -11982,8 +11975,8 @@ the default value.
 @node Key bindings & useful functions, Batch execution, Noweb reference syntax, Working With Source Code
 @section Key bindings & useful functions
 
-Org-babel re-binds many common Org-mode key sequences depending on
-the context.  Within a source-code block the following sequences
+Many common Org-mode key sequences are re-bound depending on
+the context.  Within a code block the following sequences
 are rebound:
 
 @multitable @columnfractions 0.25 0.75
@@ -12022,7 +12015,7 @@ kept pressed, resulting in the following additional keybindings.
 
 @node Batch execution, , Key bindings & useful functions, Working With Source Code
 @section Batch execution
-It is possible to call Org-babel functions from the command line.  This shell
+It is possible to call functions from the command line.  This shell
 script calls @code{org-babel-tangle} on every one of its arguments.
 
 Be sure to adjust the paths to fit your system.