Merge commit 'origin/master'

lisp/org-babel-tangle.el

@@ -98,11 +98,11 @@ language."
                        by-session)
                (setq block-counter (+ block-counter (length (cdr (car by-session)))))
                (to-file (format "%s.%s" base-name ext) (cdr (car by-session)))))))
-       (org-babel-collect-blocks lang))
+       (org-babel-tangle-collect-blocks lang))
       (message "tangled %d source-code blocks" block-counter)
       path-collector)))
 
-(defun org-babel-collect-blocks (&optional lang)
+(defun org-babel-tangle-collect-blocks (&optional lang)
   "Collect all source blocks in the current org-mode file.
 Return two nested association lists, first grouped by language,
 then by session, the contents will be source-code block
@@ -123,16 +123,17 @@ code blocks by language."
              (spec (list link source-name params body))
              (session (cdr (assoc :session params)))
              by-lang by-session)
-        (unless (and lang (not (string= lang src-lang))) ;; maybe limit by language
-          ;; add the spec for this block to blocks under it's language and session
-          (setq by-lang (cdr (assoc src-lang blocks)))
-          (setq blocks (delq (assoc src-lang blocks) blocks))
-          (setq by-session (cdr (assoc session by-lang)))
-          (setq by-lang (delq (assoc session by-lang) by-lang))
-          (setq blocks (cons ;; by-language
-                        (cons src-lang (cons ;; by-session
-                                        (cons session (cons spec by-session)) by-lang))
-                        blocks)))))
+        (unless (string= (cdr (assoc :tangle params)) "no") ;; maybe skip
+          (unless (and lang (not (string= lang src-lang))) ;; maybe limit by language
+            ;; add the spec for this block to blocks under it's language and session
+            (setq by-lang (cdr (assoc src-lang blocks)))
+            (setq blocks (delq (assoc src-lang blocks) blocks))
+            (setq by-session (cdr (assoc session by-lang)))
+            (setq by-lang (delq (assoc session by-lang) by-lang))
+            (setq blocks (cons ;; by-language
+                          (cons src-lang (cons ;; by-session
+                                          (cons session (cons spec by-session)) by-lang))
+                          blocks))))))
     ;; blocks should contain all source-blocks organized by language and session
     ;; (message "blocks=%S" blocks) ;; debugging
     blocks))

lisp/org-babel.el

@@ -497,7 +497,7 @@ non-nil."
 elements of PLISTS override the values of previous element.  This
 takes into account some special considerations for certain
 parameters when merging lists."
-  (let (params results exports vars var ref)
+  (let (params results exports tangle vars var ref)
     (flet ((e-merge (exclusive-groups &rest result-params)
                     ;; maintain exclusivity of mutually exclusive parameters
                     (let (output)
@@ -525,20 +525,25 @@ parameters when merging lists."
                                  vars (cons (cons var ref) (assq-delete-all var vars)))))
                         (:results
                          (setq results (e-merge '(("file" "vector" "scalar")
-                                                  ("replace" "silent"))
+                                                  ("replace" "silent")
+                                                  ("output" "value"))
                                                 results (split-string (cdr pair)))))
                         (:exports
                          (setq exports (e-merge '(("code" "results" "both"))
                                                 exports (split-string (cdr pair)))))
+                        (:tangle
+                         (setq tangle (e-merge '(("yes" "no"))
+                                               tangle (split-string (cdr pair)))))
                         (t ;; replace: this covers e.g. :session
                          (setq params (cons pair (assq-delete-all (car pair) params))))))
                     plist))
             plists))
     (setq vars (mapcar (lambda (pair) (format "%s=%s" (car pair) (cdr pair))) vars))
     (while vars (setq params (cons (cons :var (pop vars)) params)))
-    (cons (cons :exports (mapconcat 'identity exports " "))
-          (cons (cons :results (mapconcat 'identity results " "))
-                params))))
+    (cons (cons :tangle (mapconcat 'identity tangle " "))
+          (cons (cons :exports (mapconcat 'identity exports " "))
+                (cons (cons :results (mapconcat 'identity results " "))
+                      params)))))
 
 (defun org-babel-clean-text-properties (text)
   "Strip all properties from text return."

org-babel-ded-worg.org

@@ -116,4 +116,68 @@ c(5, 10)
 #+resname:
 : Sun Jul  5 14:13:07 2009
 
-    
+* Reference / Documentation
+
+*** Source Code block syntax
+
+The basic syntax of source-code blocks is as follows:
+
+: #+srcname: name
+: #+begin_src language header-arguments
+: body
+: #+end_src
+
+- name :: This name is associated with the source-code block.  This is
+     similar to the =#+TBLNAME= lines which can be used to name tables
+     in org-mode files.  By referencing the srcname of a source-code
+     block it is possible to evaluate the block for other places,
+     files, or from inside tables.
+- language :: The language of the code in the source-code block, valid
+     values must be members of `org-babel-interpreters'.
+- header-arguments :: Header arguments control many facets of the
+     input to, evaluation of, and output of source-code blocks.  See
+     the [[* Header Arguments][Header Arguments]] section for a complete review of available
+     header arguments.
+- body :: The actual source code which will be evaluated.  This can be
+          edited with `org-edit-special'.
+
+**** Header Arguments
+
+- results :: results arguments specify what should be done with the
+             output of source-code blocks
+  - The following options are mutually exclusive, and specify how the
+    results should be collected from the source-code block
+    - value ::
+    - output :: 
+  - The following options are mutually exclusive and specify what type
+    of results the code block will return
+    - vector :: specifies that the results should be interpreted as a
+                multidimensional vector (even if the vector is
+                trivial), and will be inserted into the org-mode file
+                as a table
+    - scalar :: specifies that the results should be interpreted as a
+                scalar value, and will be inserted into the org-mode
+                file as quoted text
+    - file :: specifies that the results should be interpreted as the
+              path to a file, and will be inserted into the org-mode
+              file as a link
+  - The following options specify how the results should be inserted
+    into the org-mode file
+    - replace :: the current results replace any previously inserted
+                 results from the code block
+    - silent :: rather than being inserted into the org-mode file the
+                results are echoed into the message bar
+- exports :: exports arguments specify what should be included in html
+             or latex exports of the org-mode file
+  - code :: the body of code is included into the exported file
+  - results :: the results of evaluating the code is included in the
+               exported file
+  - both :: both the code and results are included in the exported
+            file
+  - none :: nothing is included in the exported file
+- 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
+

org-babel.org

@@ -207,7 +207,7 @@ would then be [[#sandbox][the sandbox]].
 #+end_src
 
 
-* Tasks [36/57]
+* Tasks [37/58]
 ** PROPOSED raise elisp error when source-blocks return errors
 Not sure how/if this would work, but it may be desirable.
 
@@ -256,6 +256,7 @@ but with preference given to
 ** TODO make tangle files read-only?
    With a file-local variable setting, yea that makes sense.  Maybe
    the header should reference the related org-mode file.
+
 ** TODO take default values for header args from properties
    Use file-wide and subtree wide properties to set default values for
    header args.
@@ -931,6 +932,12 @@ to the command if BUFF is not given.)
     2) The function is called inside of a =write.table= function call
        writing the results to a table
     3) The table is read using =org-table-import=
+** DONE add =:tangle= family of header arguments
+values are
+- no :: don't include source-code block when tangling
+- yes :: do include source-code block when tangling
+
+this is tested in [[file:test-tangle.org::*Emacs%20Lisp%20initialization%20stuff][test-tangle.org]]
 
 ** DONE Default args
    This would be good thing to address soon. I'm imagining that

test-tangle.org

@@ -85,3 +85,8 @@ plus_two(holder)
   (setq test-tangle-loading "org-babel tangles")
   (setq test-tangle-advert "use org-babel-tangle for all your emacs initialization files!!")
 #+end_src
+
+#+srcname: i-shouldnt-be-tangled
+#+begin_src emacs-lisp :tangle no
+  (setq test-tangle-i-should-not-exist "hopefully I'm not included")
+#+end_src