From 96016821bae1f52bd42b09518b3606069ce21a9b Mon Sep 17 00:00:00 2001
From: Eric Schulte <schulte.eric@gmail.com>
Date: Thu, 30 Jul 2009 20:18:34 -0600
Subject: [PATCH] updated documentation for new tangling syntax

  and re-ordered the tasks
---
 org-babel-worg.org | 10 +++++--
 org-babel.org      | 66 +++++++++++++++++++++++-----------------------
 2 files changed, 41 insertions(+), 35 deletions(-)

diff --git a/org-babel-worg.org b/org-babel-worg.org
index eeb234b78..8233a5ce9 100644
--- a/org-babel-worg.org
+++ b/org-babel-worg.org
@@ -141,6 +141,12 @@ The basic syntax of source-code blocks is as follows:
 - tangle :: tangle arguments specify whether or not the source-code
             block should be included in tangled extraction of
             source-code files
-  - on :: the source-code block is included in tangled files
-  - off :: the source-code block is ignored when tangling
+  - yes :: the source-code block is exported to a source-code file
+           named after the basename (name w/o extension) of the
+           org-mode file
+  - no :: (default) the source-code block is not exported to a
+          source-code file
+  - other :: any other string passed to the =tangle= header argument
+             is interpreted as a file basename to which the block will
+             be exported
 
diff --git a/org-babel.org b/org-babel.org
index 3a895886f..63de8b9c2 100644
--- a/org-babel.org
+++ b/org-babel.org
@@ -240,39 +240,6 @@ being generated at =ruby-nuweb.rb= with the following contents
 : puts "                            Ruby                            "
 : puts "---------------------------footer---------------------------"
 
-** DONE re-work tangling system
-Sometimes when tangling a file (e.g. when extracting elisp from a
-org-mode file) we want to get nearly every source-code block.
-
-Sometimes we want to only extract those source-code blocks which
-reference a indicate that they should be extracted (e.g. traditional
-literate programming along the Nuweb model)
-
-I'm not sure how we can devise a single simple tangling system that
-naturally fits both of these use cases.
-
-*** new setup
-the =tangle= header argument will default to =no= meaning source-code
-blocks will *not* be exported by default.  In order for a source-code
-block to be tangled it needs to have an output file specified.  This
-can happen in two ways...
-
-1) a file-wide default output file can be passed to `org-babel-tangle'
-   which will then be used for all blocks
-2) if the value of the =tangle= header argument is anything other than
-   =no= or =yes= then it is used as the file name
-
-#+srcname: test-new-tangling
-#+begin_src emacs-lisp 
-  (org-babel-load-file "test-tangle.org")
-  (if (string= test-tangle-advert "use org-babel-tangle for all your emacs initialization files!!")
-      "succeed"
-    "fail")
-#+end_src
-
-#+resname:
-: succeed
-
 ** PROPOSED raise elisp error when source-blocks return errors
 Not sure how/if this would work, but it may be desirable.
 
@@ -1206,6 +1173,39 @@ to the command if BUFF is not given.)
        writing the results to a table
     3) The table is read using =org-table-import=
 
+** DONE re-work tangling system
+Sometimes when tangling a file (e.g. when extracting elisp from a
+org-mode file) we want to get nearly every source-code block.
+
+Sometimes we want to only extract those source-code blocks which
+reference a indicate that they should be extracted (e.g. traditional
+literate programming along the Nuweb model)
+
+I'm not sure how we can devise a single simple tangling system that
+naturally fits both of these use cases.
+
+*** new setup
+the =tangle= header argument will default to =no= meaning source-code
+blocks will *not* be exported by default.  In order for a source-code
+block to be tangled it needs to have an output file specified.  This
+can happen in two ways...
+
+1) a file-wide default output file can be passed to `org-babel-tangle'
+   which will then be used for all blocks
+2) if the value of the =tangle= header argument is anything other than
+   =no= or =yes= then it is used as the file name
+
+#+srcname: test-new-tangling
+#+begin_src emacs-lisp 
+  (org-babel-load-file "test-tangle.org")
+  (if (string= test-tangle-advert "use org-babel-tangle for all your emacs initialization files!!")
+      "succeed"
+    "fail")
+#+end_src
+
+#+resname:
+: succeed
+
 ** DONE =\C-c \C-o= to open results of source block
 by adding a =defadvice= to =org-open-at-point= we can use the common
 =\C-c \C-o= keybinding to open the results of a source-code block.