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

pushing through first half or so of babel documentation, compiling

Eric Schulte 15 years ago
parent
9e8b6c0831
commit
d7b2397184
1 changed files with 102 additions and 104 deletions
Unified View Show Diff Stats
  1. 102 104
      doc/org.texi

+ 102 - 104
doc/org.texi
View File 

@@ -10847,7 +10847,7 @@ This may be necessary in particular if files include other files via
 
 @node Working With Source Code, Miscellaneous, Publishing, Top
 
 @node Working With Source Code, Miscellaneous, Publishing, Top
 
 @comment  node-name,  next,  previous,  up
 
 @comment  node-name,  next,  previous,  up
 
 @comment Working With Source Code, Miscellaneous, Publishing, Top
 
 @comment Working With Source Code, Miscellaneous, Publishing, Top
 
-@chapter ``Working With Source Code'' or ``Embedded Source Code''
 
+@chapter Working With Source Code
 
 
 
 Source code can be included in Org-mode documents using a @samp{src} block:
 
 Source code can be included in Org-mode documents using a @samp{src} block:
 
 
 
@@ -10880,6 +10880,11 @@ Using code blocks in table formulas
 
 * Exporting Code Blocks::       
 * Exporting Code Blocks::       
 * Extracting Source Code::      
 * Extracting Source Code::      
 * Evaluating Code Blocks::      
 * Evaluating Code Blocks::      
+* Library of Babel::
 
+* Languages::
 
+* Header Arguments::
 
+* Noweb Reference Syntax::
 
+* Key Bindings & Useful Functions::
 
 @end menu
 
 @end menu
 
 
 
 
 
@@ -10899,16 +10904,21 @@ The structure of code blocks is as follows:
 
 
 
 @table @code
 
 @table @code
 
 @item <name>
 
 @item <name>
 
-An optional name for the block (see @ref{Evaluating Code Blocks})
 
+This name is associated with the source 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 source code block makes it possible to evaluate the
 
+block from other places in the file, other files, or from inside of Org-mode
 
+tables.
 
 @item <language>
 
 @item <language>
 
 The language of the code in the block.
 
 The language of the code in the block.
 
 @item <switches>
 
 @item <switches>
 
-Optional links FIXME link/relocate switches discussion in @ref{Literal examples}
 
+Switches controling exportation of the code block (see switches discussion in
 
+@ref{Literal examples})
 
 @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 source code blocks. See the [[header-arguments][Header
 
-Arguments]] section. Header arguments can also be set on a per-buffer or
 
-per-subtree basis using properties.
 
+tangling of source code blocks. See the @ref{Header Arguments}
 
+section. Header arguments can also be set on a per-buffer or per-subtree
 
+basis using properties.
 
 @item <body>
 
 @item <body>
 
 The code
 
 The code
 
 @end table
 
 @end table
 
@@ -10923,10 +10933,10 @@ major-mode edit buffer containing the body of the code block. Saving this
 
 buffer will write the new contents back to the Org buffer. Use @kbd{C-c '}
 
 buffer will write the new contents back to the Org buffer. Use @kbd{C-c '}
 
 again to exit.
 
 again to exit.
 
 
 
-The edit buffer has a minor mode active called @code{org-src-mode}. The
 
+The @code{org-src-mode} minor mode will be active in the edit buffer. The
 
 following variables can be used to configure the behavior of the edit
 
 following variables can be used to configure the behavior of the edit
 
-buffer. See also the customization group @code{org-edit-structure} for futher
 
-configuration options.
 
+buffer. See also the customization group @code{org-edit-structure} for
 
+further configuration options.
 
 
 
 @table @code
 
 @table @code
 
 @item org-src-lang-modes
 
 @item org-src-lang-modes
 
@@ -10937,7 +10947,7 @@ can be used to map arbitrary language names to existing major modes.
 
 @item org-src-window-setup
 
 @item org-src-window-setup
 
 Controls the way Emacs windows are rearranged when the edit buffer is created.
 
 Controls the way Emacs windows are rearranged when the edit buffer is created.
 
 @item org-src-preserve-indentation
 
 @item org-src-preserve-indentation
 
-This variable is expecially useful for tangling languages such as
 
+This variable is especially useful for tangling languages such as
 
 python, in which whitespace indentation in the output is critical.
 
 python, in which whitespace indentation in the output is critical.
 
 @item org-src-ask-before-returning-to-edit-buffer
 
 @item org-src-ask-before-returning-to-edit-buffer
 
 By default, Org will ask before returning to an open edit buffer. Set
 
 By default, Org will ask before returning to an open edit buffer. Set
 
@@ -10949,31 +10959,31 @@ to a non-nil value to switch without asking.
 
 @comment  Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code
 
 @comment  Exporting Code Blocks, Extracting Source Code, Editing Source Code, Working With Source Code
 
 @section Exporting Code Blocks
 
 @section Exporting Code Blocks
 
 
 
-By default, code blocks export to HTML with the appearance of the fontified
 
-language major-mode Emacs buffer
 
+It is possible to export the contents of code blocks, the results of code
 
+block evaluation, or neither or both.  For most languages by default only
 
+body of a code blocks will be exported, however some languages
 
+(e.g. @code{ditaa}) default to exporting the results of the code block.  For
 
+information on the exportation of code blocks bodies see @ref{Literal
 
+examples}.
 
 
 
-FIXME: say something more knowledgable about the HTML/CSS output.
 
-
 
-A similar effect is possible with LaTeX if you turn on
 
-the option @code{org-export-latex-listings} and make sure that the listings
 
-package is included by the LaTeX header FIXME: be more specific about latex
 
-config.
 
-
 
-FIXME: This duplicated discussion in @ref{Literal examples}. Add
 
-documentation of relevant switches.
 
-
 
-The @code{:exports} header argument can be used to specify non-default export behavior:
 
+The @code{:exports} header argument can be used to specify non-default export
 
+behavior:
 
 
 
+Header arguments:
 
 @table @code
 
 @table @code
 
 @item :exports results
 
 @item :exports results
 
-On export, the code block will be executed and the block will be replaced by
 
-the results of the code block (as determined by the values of other header
 
-arguments such as @code{results} and @code{file}.
 
+On export, the code block will be evaluated and the results will be placed in
 
+the org-mode buffer (either updating previous results of the code block
 
+located anywhere in the buffer, or if no previous results exist placing the
 
+new results immediately after the code block).  The actual body of the code
 
+block will not be exported.
 
 @item :exports both
 
 @item :exports both
 
-On export, the code block will be executed and the exported material will
 
-contain the code, followed by the results.
 
+On export, the code block will be evaluated and the results inserted into the
 
+buffer as described above, however the body of the code block will be
 
+exported as well.
 
 @item :exports code
 
 @item :exports code
 
-The default. The body of the code block is exported as described above.
 
+The default (in most languages). Only the body of the code block is exported
 
+as described in @ref{Literal examples}.
 
 @end table
 
 @end table
 
 
 
 @node Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code
 
 @node Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code
 
@@ -10981,8 +10991,11 @@ The default. The body of the code block is exported as described above.
 
 @comment  Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code
 
 @comment  Extracting Source Code, Evaluating Code Blocks, Exporting Code Blocks, Working With Source Code
 
 @section Extracting Source Code
 
 @section Extracting Source Code
 
 
 
-Creating monolingual code files by extracting code from source blocks is
 
-referred to as ``tangling''.
 
+Creating pure source code files by extracting code from source blocks is
 
+referred to as ``tangling'' -- a term adopted from the literate programming
 
+community.  During ``tangling'' of code blocks their bodies are expanded
 
+using @code{org-babel-expand-src-block} which can expand both variable and
 
+``noweb'' (see @ref{Noweb Reference Syntax}) style references.
 
 
 
 Header arguments:
 
 Header arguments:
 
 @table @code
 
 @table @code
 
@@ -10990,7 +11003,8 @@ Header arguments:
 
 The default.
 
 The default.
 
 @item :tangle yes
 
 @item :tangle yes
 
 Include block in tangled output. The output file name is the name of the org
 
 Include block in tangled output. The output file name is the name of the org
 
-file with the extension @samp{.org} replaced by the extension for the block language.
 
+file with the extension @samp{.org} replaced by the extension for the block
 
+language.
 
 @item :tangle filename
 
 @item :tangle filename
 
 Include block in tangled output to file @samp{filename}
 
 Include block in tangled output to file @samp{filename}
 
 @end table
 
 @end table
 
@@ -11010,76 +11024,60 @@ FIXME: This variable may have been changed recently
 
 @end table
 
 @end table
 
 
 
 
 
-
 
-@node Evaluating Code Blocks,  , Extracting Source Code, Working With Source Code
 
+@node Evaluating Code Blocks, Library of Babel, Extracting Source Code, Working With Source Code
 
 @comment  node-name,  next,  previous,  up
 
 @comment  node-name,  next,  previous,  up
 
 @comment  Evaluating Code Blocks,  , Extracting Source Code, Working With Source Code
 
 @comment  Evaluating Code Blocks,  , Extracting Source Code, Working With Source Code
 
 @section Evaluating Code Blocks
 
 @section Evaluating Code Blocks
 
 
 
-For many languages, blocks of code can be evaluated, with the results being
 
-returned to the org buffer (or linked to from the org buffer).
 
+For many language, blocks of code can be evaluated and the results
 
+incorporated into the org-mode buffer.  Check the value of the
 
+@code{org-babel-interpreters} for a list of evaluable languages on your
 
+system, also see @ref{Languages}.  See @ref{Structure of Code Blocks} for
 
+information on the syntax used to define a code block.
 
 
 
-FIXME: Are we going to use ``evaluate'' or ``execute''
 
+There are a number of ways of evaluating code blocks.  The simplest is to
 
+press @key{C-c C-c} with the point on a code block.  This will call the
 
+@code{org-babel-execute-src-block} function evaluating the block and
 
+inserting its results into the Org-mode buffer.
 
 
 
-This syntax can be expanded by naming the source code block.
 
+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}).  Both of these lines use the following syntax.
 
 
 
 @example
 
 @example
 
-#+sourcename
 
-#+begin_src language header-arguments switches
 
-body
 
-#+end_src
 
+#+call: <name>(<arguments>) <header arguments>
 
 @end example
 
 @end example
 
 
 
-- name :: This name is associated with the source code block.  This is
 
-     similar to the =#+tblname= lines that can be used to name tables
 
-     in Org-mode files.  Referencing the name of a source code
 
-     block makes it possible to evaluate the block from other places in
 
-     the file, other files, or inside Org-mode tables.  It
 
-     is also possible to pass arguments to a source code block through
 
-     this =#+source:= line (see [[alternate-argument-syntax][Alternate argument syntax]]).
 
-
 
-@subsection Library of Babel
 
-[[file:library-of-babel.org][Library of Babel]] functions can be called using the following syntax.
 
-
 
-@example
 
-#+lob: R-plot(data=R-plot-example-data)
 
-@end example
 
-
 
-@subsection Aliases
 
-   Keyword aliases are intended to make Org-babel feel natural to
 
-   programmers fluent in a variety of languages.  For example,
 
-   @example
 
-     #+srcname: alias-example
 
-     #+begin_src emacs-lisp
 
-       '((call lob)
 
-         (source function srcname)
 
-         (results resname))
 
-     #+end_src
 
-
 
-     #+results: alias-example
 
-     | call    | lob      |         |
 
-     | source  | function | srcname |
 
-     | results | resname  |         |
 
-   @end example
 
-     - =#+srcname:= can be replaced with either of two aliases,  =#+source:= or =#+function:=.
 
-     - =#+results:= can be replaced with its alias, =#+resname:=.
 
-
 
-   When calling Library of Babel functions, as in the following
 
-   example, there are two acceptable keywords.  The =#+lob= call in
 
-   the example could be replaced with its alias, =#+call=.
 
-   @example
 
-     #+lob: R-plot(data=R-plot-example-data)
 
-   @end example
 
-
 
-@subsection Languages
 
-  :PROPERTIES:
 
-  :CUSTOM_ID: languages
 
-  :END:
 
+@table @code
 
+@item <name>
 
+This name is associated with the source code block to be evaluated.
 
+@item <arguments>
 
+Arguments specified in this section will be passed to the code block.
 
+@item <header arguments>
 
+Header arguments can be placed after the function invocation.  See
 
+@ref{Header Arguments} for more information on header arguments.
 
+@end table
 
+
 
 
 
-Org-babel can evaluate/execute/compile the following languages. See the
 
-language specific documentation on Worg for details.
 
+@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
 
+which 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 contributed functions which they believe to be
 
+generally useful.  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).
 
 
 
-FIXME: How are we going to refer to the external documentation?
 
+
 
+@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}.
 
 
 
 @c BEGIN RECEIVE ORGTBL org-babel-lang-table
 
 @c BEGIN RECEIVE ORGTBL org-babel-lang-table
 
 @multitable @columnfractions 0.583 0.417
 
 @multitable @columnfractions 0.583 0.417
 
@@ -11135,7 +11133,7 @@ The original table from reference.org is below; I'm just using the first column
 
   | Ruby           | ruby       |
 
   | Ruby           | ruby       |
 
   | Sass           | sass       |
 
   | Sass           | sass       |
 
   | GNU Screen     | screen     |
 
   | GNU Screen     | screen     |
 
-  | shell          | sh[fn:1]   |
 
+  | shell          | sh         |
 
   | SQL            | sql        |
 
   | SQL            | sql        |
 
 
 
 
 
@@ -11167,15 +11165,17 @@ The original table from reference.org is below; I'm just using the first column
 
 
 
 @end ignore
 
 @end ignore
 
 
 
-To add support for a particular language to your Org-babel 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 entries in the Identifier column of the table).
 
+To add support for a particular language to your Org-babel 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).
 
 
 
 @example
 
 @example
 
 (require 'org-babel-identifier)
 
 (require 'org-babel-identifier)
 
 @end example
 
 @end example
 
 
 
+
 
+@node Header Arguments, Noweb Reference Syntax, Languages, Working With Source Code
 
 @section Header Arguments
 
 @section Header Arguments
 
     :PROPERTIES:
 
     :PROPERTIES:
 
     :CUSTOM_ID: header-arguments
 
     :CUSTOM_ID: header-arguments
 
@@ -11552,7 +11552,7 @@ heading:
 
 
 
 @subsubheading Remote execution
 
 @subsubheading Remote execution
 
      A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp
 
      A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp
 
-     filename syntax]], in which case the code will be executed on the
 
+     filename syntax]], in which case the code will be evaluated on the
 
      remote machine[fn:2]. An example is
 
      remote machine[fn:2]. An example is
 
 
 
 @example 
 @example 
@@ -11694,7 +11694,7 @@ above features to work correctly.
 
     results to avoid re-running unchanged source code blocks.  This
 
     results to avoid re-running unchanged source code blocks.  This
 
     header argument can have one of two values: =yes= or =no=.
 
     header argument can have one of two values: =yes= or =no=.
 
     - =no= :: The default.  No caching takes place and the source
 
     - =no= :: The default.  No caching takes place and the source
 
-         code block will be run every time it is executed.
 
+         code block will be run every time it is evaluated.
 
     - =yes= :: every time the source code block is run a sha1 hash of
 
     - =yes= :: every time the source code block is run a sha1 hash of
 
          the code and arguments passed to the block will be
 
          the code and arguments passed to the block will be
 
          generated.  This hash is packed into the =#+results:= line
 
          generated.  This hash is packed into the =#+results:= line
 
@@ -11790,11 +11790,9 @@ above features to work correctly.
 
        and prints out its value, '2'. (Indeed, the other print statements are
 
        and prints out its value, '2'. (Indeed, the other print statements are
 
        unnecessary here).
 
        unnecessary here).
 
 
 
-@section Noweb Reference Syntax
 
-  :PROPERTIES:
 
-  :CUSTOM_ID: noweb-reference-syntax
 
-  :END:
 
 
 
+@node Noweb Reference Syntax, Key Bindings & Useful Functions, Header Arguments, Working With Source Code
 
+@section Noweb Reference Syntax
 
   The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to
 
   The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to
 
   be referenced by using the familiar Noweb syntax:
 
   be referenced by using the familiar Noweb syntax:
 
   : <<code-block-name>>
 
   : <<code-block-name>>
 
@@ -11820,6 +11818,8 @@ above features to work correctly.
 
   An example that uses the Noweb reference syntax is provided in the
 
   An example that uses the Noweb reference syntax is provided in the
 
   [[literate programming example]].
 
   [[literate programming example]].
 
 
 
+
 
+@node Key Bindings & Useful Functions, , Noweb Reference Syntax, Working With Source Code
 
 @section Key Bindings & Useful Functions
 
 @section Key Bindings & Useful Functions
 
 
 
   Org-babel re-binds many common Org-mode key sequences depending on
 
   Org-babel re-binds many common Org-mode key sequences depending on
 
@@ -11864,7 +11864,7 @@ above features to work correctly.
 
 
 
   (org-babel-execute-src-block &optional ARG INFO PARAMS)
 
   (org-babel-execute-src-block &optional ARG INFO PARAMS)
 
 
 
-  Execute the current source code block, and insert the results
 
+  Evaluate the current source code block, and insert the results
 
   into the buffer.  Source code execution and the collection and
 
   into the buffer.  Source code execution and the collection and
 
   formatting of results can be controlled through a variety of
 
   formatting of results can be controlled through a variety of
 
   header arguments.
 
   header arguments.
 
@@ -14216,8 +14216,6 @@ org-customize @key{RET}} and then click yourself through the tree.
 
 @end ignore
 
 @end ignore
 
 
 
 @c Local variables:
 
 @c Local variables:
 
-@c ispell-local-dictionary: "en_US-w_accents"
 
-@c ispell-local-pdict: "./.aspell.org.pws"
 
 @c fill-column: 77
 
 @c fill-column: 77
 
 @c End:
 
 @c End: