summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTom Dye <tsd@tsdye.com>2010-07-13 16:20:08 -0700
committerEric Schulte <schulte.eric@gmail.com>2010-07-13 16:20:08 -0700
commit272aefce838d8948cd69f5b5443bf11ec82ffcca (patch)
tree2e3a01aa4a8bc6c3d3973bd966132e1cf38c1bf2
parent3807787aa99797798db2663f49c8fae9dfa9718e (diff)
downloadorg-mode-272aefce838d8948cd69f5b5443bf11ec82ffcca.tar.gz
Finished editing Babel docstrings
-rw-r--r--lisp/ob-gnuplot.el17
-rw-r--r--lisp/ob-haskell.el21
-rw-r--r--lisp/ob-keys.el13
-rw-r--r--lisp/ob-latex.el18
-rw-r--r--lisp/ob-lob.el27
-rw-r--r--lisp/ob-mscgen.el10
-rw-r--r--lisp/ob-ocaml.el14
-rw-r--r--lisp/ob-octave.el41
-rw-r--r--lisp/ob-perl.el19
-rw-r--r--lisp/ob-python.el29
-rw-r--r--lisp/ob-ref.el39
-rw-r--r--lisp/ob-ruby.el25
-rw-r--r--lisp/ob-sass.el6
-rw-r--r--lisp/ob-screen.el10
-rw-r--r--lisp/ob-sh.el28
-rw-r--r--lisp/ob-sql.el6
-rw-r--r--lisp/ob-sqlite.el7
-rw-r--r--lisp/ob-table.el7
-rw-r--r--lisp/ob-tangle.el29
-rw-r--r--lisp/ob.el182
20 files changed, 295 insertions, 253 deletions
diff --git a/lisp/ob-gnuplot.el b/lisp/ob-gnuplot.el
index 4e0aef6..1f4878f 100644
--- a/lisp/ob-gnuplot.el
+++ b/lisp/ob-gnuplot.el
@@ -58,8 +58,8 @@
(defvar org-babel-gnuplot-timestamp-fmt nil)
(defun org-babel-gnuplot-process-vars (params)
- "Extract variables from PARAMS and process the variables
-dumping all vectors into files and returning an association list
+ "Extract variables from PARAMS and process the variables.
+Dumps all vectors into files and returns an association list
of variable names and the related value to be used in the gnuplot
code."
(mapcar
@@ -130,8 +130,8 @@ code."
body)))
(defun org-babel-execute:gnuplot (body params)
- "Execute a block of Gnuplot code with org-babel. This function is
-called by `org-babel-execute-src-block'."
+ "Execute a block of Gnuplot code.
+This function is called by `org-babel-execute-src-block'."
(require 'gnuplot)
(let ((session (cdr (assoc :session params)))
(result-type (cdr (assoc :results params)))
@@ -157,7 +157,7 @@ called by `org-babel-execute-src-block'."
out-file))))
(defun org-babel-prep-session:gnuplot (session params)
- "Prepare SESSION according to the header arguments specified in PARAMS."
+ "Prepare SESSION according to the header arguments in PARAMS."
(let* ((session (org-babel-gnuplot-initiate-session session))
(vars (org-babel-ref-variables params))
(var-lines (mapcar
@@ -182,7 +182,8 @@ called by `org-babel-execute-src-block'."
(defvar gnuplot-buffer)
(defun org-babel-gnuplot-initiate-session (&optional session params)
- "If there is not a current inferior-process-buffer in SESSION
+ "Initiate a gnuplot session.
+If there is not a current inferior-process-buffer in SESSION
then create one. Return the initialized session. The current
`gnuplot-mode' doesn't provide support for multiple sessions."
(require 'gnuplot)
@@ -192,13 +193,13 @@ then create one. Return the initialized session. The current
gnuplot-buffer)))
(defun org-babel-gnuplot-quote-timestamp-field (s)
- "Convert field S from timestamp to Unix time and export to gnuplot."
+ "Convert S from timestamp to Unix time and export to gnuplot."
(format-time-string org-babel-gnuplot-timestamp-fmt (org-time-string-to-time s)))
(defvar org-table-number-regexp)
(defvar org-ts-regexp3)
(defun org-babel-gnuplot-quote-tsv-field (s)
- "Quote field S for export to gnuplot."
+ "Quote S for export to gnuplot."
(unless (stringp s)
(setq s (format "%s" s)))
(if (string-match org-table-number-regexp s) s
diff --git a/lisp/ob-haskell.el b/lisp/ob-haskell.el
index e191940..e45272d 100644
--- a/lisp/ob-haskell.el
+++ b/lisp/ob-haskell.el
@@ -70,7 +70,7 @@
vars "\n") "\n" body "\n")))
(defun org-babel-execute:haskell (body params)
- "Execute a block of Haskell code with org-babel."
+ "Execute a block of Haskell code."
(let* ((processed-params (org-babel-process-params params))
(session (nth 0 processed-params))
(vars (nth 1 processed-params))
@@ -103,7 +103,8 @@
string))
(defun org-babel-haskell-initiate-session (&optional session params)
- "If there is not a current inferior-process-buffer in SESSION
+ "Initiate a haskell session.
+If there is not a current inferior-process-buffer in SESSION
then create one. Return the initialized session."
(require 'inf-haskell)
(or (get-buffer "*haskell*")
@@ -123,7 +124,7 @@ then create one. Return the initialized session."
(defun org-babel-prep-session:haskell
(session params &optional processed-params)
- "Prepare SESSION according to the header arguments specified in PARAMS."
+ "Prepare SESSION according to the header arguments in PARAMS."
(save-window-excursion
(let ((pp (or processed-params (org-babel-process-params params)))
(buffer (org-babel-haskell-initiate-session session)))
@@ -138,7 +139,8 @@ then create one. Return the initialized session."
(current-buffer))))
(defun org-babel-haskell-table-or-string (results)
- "If the results look like a table, then convert them into an
+ "Convert RESULTS to an Emacs-lisp table or string.
+If RESULTS look like a table, then convert them into an
Emacs-lisp table, otherwise return the results as a string."
(org-babel-read
(if (and (stringp results) (string-match "^\\[.+\\]$" results))
@@ -152,21 +154,22 @@ Emacs-lisp table, otherwise return the results as a string."
results)))
(defun org-babel-haskell-var-to-haskell (var)
- "Convert an elisp var into a string of haskell source code
-specifying a var of the same value."
+ "Convert an elisp value VAR into a haskell variable.
+The elisp VAR is converted to a string of haskell source code
+specifying a variable of the same value."
(if (listp var)
(concat "[" (mapconcat #'org-babel-haskell-var-to-haskell var ", ") "]")
(format "%S" var)))
(defvar org-src-preserve-indentation)
(defun org-babel-haskell-export-to-lhs (&optional arg)
- "Export to a .lhs file with all haskell code blocks escaped
-appropriately. When called with a prefix argument the resulting
+ "Export to a .lhs file with all haskell code blocks escaped.
+When called with a prefix argument the resulting
.lhs file will be exported to a .tex file. This function will
create two new files, base-name.lhs and base-name.tex where
base-name is the name of the current org-mode file.
-Note that all standard org-babel literate programming
+Note that all standard Babel literate programming
constructs (header arguments, no-web syntax etc...) are ignored."
(interactive "P")
(let* ((contents (buffer-string))
diff --git a/lisp/ob-keys.el b/lisp/ob-keys.el
index 0121c75..466408a 100644
--- a/lisp/ob-keys.el
+++ b/lisp/ob-keys.el
@@ -33,20 +33,17 @@
(require 'ob)
(defvar org-babel-key-prefix "\C-c\C-v"
- "The `org-babel-key-prefix' variable holds the key prefix
-behind which all org-babel interactive key-binding are placed.
+ "The key prefix for Babel interactive key-bindings.
See `org-babel-key-bindings' for the list of interactive babel
functions which are assigned key bindings, and see
`org-babel-map' for the actual babel keymap.")
(defvar org-babel-map (make-sparse-keymap)
- "The keymap holding key bindings for interactive org-babel
-functions.")
+ "The keymap for interactive Babel functions.")
;;;###autoload
(defun org-babel-describe-bindings ()
- "Describe all key binding placed behind the
-`org-babel-key-prefix' prefix."
+ "Describe all keybindings behind `org-babel-key-prefix'."
(interactive)
(describe-bindings org-babel-key-prefix))
@@ -79,8 +76,8 @@ functions.")
("\C-a" . org-babel-sha1-hash)
("a" . org-babel-sha1-hash)
("h" . org-babel-describe-bindings))
- "Alist associating key bindings with interactive Org-babel
-functions. This list associates interactive org-babel functions
+ "Alist of key bindings and interactive Babel functions.
+This list associates interactive Babel functions
with keys. Each element of this list will add an entry to the
`org-babel-map' using the letter key which is the `car' of the
a-list placed behind the generic `org-babel-key-prefix'.")
diff --git a/lisp/ob-latex.el b/lisp/ob-latex.el
index 65c09a1..80ef017 100644
--- a/lisp/ob-latex.el
+++ b/lisp/ob-latex.el
@@ -42,7 +42,7 @@
(defvar org-babel-default-header-args:latex
'((:results . "latex") (:exports . "results"))
- "Default arguments to use when evaluating a latex source block.")
+ "Default arguments to use when evaluating a LaTeX source block.")
(defun org-babel-expand-body:latex (body params &optional processed-params)
"Expand BODY according to PARAMS, return the expanded body."
@@ -58,8 +58,8 @@
(defvar org-format-latex-options)
(defvar org-export-latex-packages-alist)
(defun org-babel-execute:latex (body params)
- "Execute a block of Latex code with org-babel. This function is
-called by `org-babel-execute-src-block'."
+ "Execute a block of Latex code with Babel.
+This function is called by `org-babel-execute-src-block'."
(setq body (org-babel-expand-body:latex body params))
(if (cdr (assoc :file params))
(let ((out-file (cdr (assoc :file params)))
@@ -89,8 +89,8 @@ called by `org-babel-execute-src-block'."
(defvar org-export-latex-packages-alist)
(defvar org-export-latex-default-packages-alist)
(defun org-babel-latex-body-to-tex-file (tex-file body &optional height width)
- "Place the contents of BODY into TEX-FILE. Extracted from
-`org-create-formula-image' in org.el."
+ "Place the contents of BODY into TEX-FILE.
+Extracted from `org-create-formula-image' in org.el."
(with-temp-file tex-file
(insert (org-splice-latex-header
org-format-latex-header
@@ -114,8 +114,8 @@ called by `org-babel-execute-src-block'."
(defvar org-latex-to-pdf-process)
(defvar org-export-pdf-remove-logfiles)
(defun org-babel-latex-tex-to-pdf (tex-file)
- "Generate a pdf according to the contents TEX-FILE. Extracted
-from `org-export-as-pdf' in org-latex.el."
+ "Generate a pdf file according to the contents TEX-FILE.
+Extracted from `org-export-as-pdf' in org-latex.el."
(let* ((wconfig (current-window-configuration))
(default-directory (file-name-directory tex-file))
(base (file-name-sans-extension tex-file))
@@ -148,8 +148,8 @@ from `org-export-as-pdf' in org-latex.el."
pdffile)))
(defun org-babel-prep-session:latex (session params)
- "Create a session named SESSION according to PARAMS."
- (error "Latex does not support sessions"))
+ "Return an error because LaTeX doesn't support sesstions."
+ (error "LaTeX does not support sessions"))
(provide 'ob-latex)
diff --git a/lisp/ob-lob.el b/lisp/ob-lob.el
index 9f02451..5e93754 100644
--- a/lisp/ob-lob.el
+++ b/lisp/ob-lob.el
@@ -33,12 +33,13 @@
(require 'ob-table)
(defvar org-babel-library-of-babel nil
- "Library of source-code blocks. This is an association list.
-Populate the library by adding files to `org-babel-lob-files'.")
+ "Library of source-code blocks.
+This is an association list. Populate the library by adding
+files to `org-babel-lob-files'.")
(defcustom org-babel-lob-files '()
- "Files used to populate the `org-babel-library-of-babel'. To
-add files to this list use the `org-babel-lob-ingest' command."
+ "Files used to populate the `org-babel-library-of-babel'.
+To add files to this list use the `org-babel-lob-ingest' command."
:group 'org-babel
:type 'list)
@@ -55,23 +56,22 @@ add files to this list use the `org-babel-lob-ingest' command."
(assq-delete-all source-name org-babel-library-of-babel)))))))
(defconst org-babel-lob-call-aliases '("lob" "call")
- "These can be used interchangeably to call a source block
- function. If you change the value of this variable then your
- files may become unusable by other org-babel users, and vice
- versa.")
+ "Aliases to call a source block function.
+If you change the value of this variable then your files may
+ become unusable by other org-babel users, and vice versa.")
(defconst org-babel-lob-one-liner-regexp
(concat "^\\([ \t]*\\)#\\+\\(?:"
(mapconcat #'regexp-quote org-babel-lob-call-aliases "\\|")
"\\):[ \t]+\\([^\(\)\n]+\\)\(\\([^\n]*\\)\)[ \t]*\\([^\n]*\\)")
- "Regexp to match calls to predefined source block functions")
+ "Regexp to match calls to predefined source block functions.")
;; functions for executing lob one-liners
;;;###autoload
(defun org-babel-lob-execute-maybe ()
- "Detect if this is context for a org-babel Library Of Babel
-src-block and if so then run the appropriate source block from
-the Library."
+ "Execute a Library of Babel source block, if appropriate.
+Detect if this is context for a Library Of Babel source block and
+if so then run the appropriate source block from the Library."
(interactive)
(let ((info (org-babel-lob-get-info)))
(if (nth 0 info) (progn (org-babel-lob-execute info) t) nil)))
@@ -80,8 +80,7 @@ the Library."
;;;###autoload
(defun org-babel-lob-get-info ()
- "Return the function call supplied on the current Library of
-Babel line as a string.
+ "Return a Library of Babel function call as a string.
This function is analogous to org-babel-get-src-block-name. For
both functions, after they are called, (match-string 1) matches
diff --git a/lisp/ob-mscgen.el b/lisp/ob-mscgen.el
index 8428ce6..d8c96c8 100644
--- a/lisp/ob-mscgen.el
+++ b/lisp/ob-mscgen.el
@@ -66,10 +66,10 @@
"Expand BODY according to PARAMS, return the expanded body." body)
(defun org-babel-execute:mscgen (body params)
- "Execute a block of Mscgen code with org-babel. This function
-is called by `org-babel-execute-src-block'. Default filetype is
-png. Modify by setting :filetype parameter to mscgen supported
-formats."
+ "Execute a block of Mscgen code with Babel.
+This function is called by `org-babel-execute-src-block'.
+Default filetype is png. Modify by setting :filetype parameter to
+mscgen supported formats."
(let* ((out-file (or (cdr (assoc :file params)) "output.png" ))
(filetype (or (cdr (assoc :filetype params)) "png" )))
(unless (cdr (assoc :file params))
@@ -79,7 +79,7 @@ ERROR: no output file specified. Add \":file name.png\" to the src header"))
out-file))
(defun org-babel-prep-session:mscgen (session params)
- "Prepare SESSION according to PARAMS."
+ "Raise an error because Mscgen doesn't support sessions."
(error "Mscgen does not support sessions"))
(provide 'ob-mscgen)
diff --git a/lisp/ob-ocaml.el b/lisp/ob-ocaml.el
index 8cdffc9..5ca9b7e 100644
--- a/lisp/ob-ocaml.el
+++ b/lisp/ob-ocaml.el
@@ -59,7 +59,7 @@
vars "\n") "\n" body "\n")))
(defun org-babel-execute:ocaml (body params)
- "Execute a block of Ocaml code with org-babel."
+ "Execute a block of Ocaml code with Babel."
(let* ((processed-params (org-babel-process-params params))
(vars (nth 1 processed-params))
(full-body (org-babel-expand-body:ocaml body params processed-params))
@@ -78,7 +78,7 @@
(defvar tuareg-interactive-buffer-name)
(defun org-babel-prep-session:ocaml (session params)
- "Prepare SESSION according to the header arguments specified in PARAMS."
+ "Prepare SESSION according to the header arguments in PARAMS."
(require 'tuareg)
(let ((tuareg-interactive-buffer-name (if (and (not (string= session "none"))
(not (string= session "default"))
@@ -89,8 +89,8 @@
(get-buffer tuareg-interactive-buffer-name))))
(defun org-babel-ocaml-parse-output (output)
- "Parse OUTPUT where OUTPUT is string output from an ocaml
-process."
+ "Parse OUTPUT.
+OUTPUT is string output from an ocaml process."
(let ((regexp "%s = \\(.+\\)$"))
(cond
((string-match (format regexp "string") output)
@@ -105,7 +105,8 @@ process."
(t (message "don't recognize type of %s" output) output))))
(defun org-babel-ocaml-read-list (results)
- "If the results look like a table, then convert them into an
+ "Convert RESULTS into an elisp table or string.
+If the results look like a table, then convert them into an
Emacs-lisp table, otherwise return the results as a string."
(org-babel-read
(if (and (stringp results) (string-match "^\\[.+\\]$" results))
@@ -118,7 +119,8 @@ Emacs-lisp table, otherwise return the results as a string."
results)))
(defun org-babel-ocaml-read-array (results)
- "If the results look like a table, then convert them into an
+ "Convert RESULTS into an elisp table or string.
+If the results look like a table, then convert them into an
Emacs-lisp table, otherwise return the results as a string."
(org-babel-read
(if (and (stringp results) (string-match "^\\[.+\\]$" results))
diff --git a/lisp/ob-octave.el b/lisp/ob-octave.el
index ab60932..f7ae2dc 100644
--- a/lisp/ob-octave.el
+++ b/lisp/ob-octave.el
@@ -43,9 +43,9 @@
(defvar org-babel-default-header-args:octave '())
(defvar org-babel-matlab-shell-command "matlab -nosplash"
- "Shell command to use to run matlab as an external process.")
+ "Shell command to run matlab as an external process.")
(defvar org-babel-octave-shell-command "octave -q"
- "Shell command to use to run octave as an external process.")
+ "Shell command to run octave as an external process.")
(defun org-babel-expand-body:matlab (body params &optional processed-params)
"Expand BODY according to PARAMS, return the expanded body."
@@ -62,9 +62,9 @@
vars "\n") "\n" body "\n")))
(defvar org-babel-matlab-with-emacs-link nil
- "If non-nil use matlab-shell-run-region for session
- evaluation. This will use EmacsLink if (matlab-with-emacs-link)
- evaluates to a non-nil value.")
+ "If non-nil use matlab-shell-run-region for session evaluation.
+ This will use EmacsLink if (matlab-with-emacs-link) evaluates
+ to a non-nil value.")
(defvar org-babel-matlab-emacs-link-wrapper-method
"%s
@@ -84,11 +84,11 @@ end")
(defvar org-babel-octave-eoe-output "ans = org_babel_eoe")
(defun org-babel-execute:matlab (body params)
- "Execute a block of matlab code with org-babel."
+ "Execute a block of matlab code with Babel."
(require 'matlab)
(org-babel-execute:octave body params 'matlab))
(defun org-babel-execute:octave (body params &optional matlabp)
- "Execute a block of octave code with org-babel."
+ "Execute a block of octave code with Babel."
(let* ((processed-params (org-babel-process-params params))
(session
(funcall (intern (format "org-babel-%s-initiate-session"
@@ -115,7 +115,7 @@ end")
(require 'matlab)
(org-babel-prep-session:octave session params 'matlab))
(defun org-babel-octave-var-to-octave (var)
- "Convert an emacs-lisp variable into an octave variable.
+ "Convert an emacs-lisp value into an octave variable.
Converts an emacs-lisp variable into a string of octave code
specifying a variable of the same value."
(if (listp var)
@@ -139,15 +139,15 @@ specifying a variable of the same value."
session))
(defun org-babel-matlab-initiate-session (&optional session params)
- "Create a matlab inferior process buffer. If there is not a
-current inferior-process-buffer in SESSION then create. Return
-the initialized session."
+ "Create a matlab inferior process buffer.
+If there is not a current inferior-process-buffer in SESSION then
+create. Return the initialized session."
(require 'matlab)
(org-babel-octave-initiate-session session params 'matlab))
(defun org-babel-octave-initiate-session (&optional session params matlabp)
- "Create an octave inferior process buffer. If there is not a
-current inferior-process-buffer in SESSION then create. Return
-the initialized session."
+ "Create an octave inferior process buffer.
+If there is not a current inferior-process-buffer in SESSION then
+create. Return the initialized session."
(require 'octave-inf)
(unless (string= session "none")
(let ((session (or session
@@ -162,10 +162,10 @@ the initialized session."
(defun org-babel-octave-evaluate
(session body result-type lang &optional matlabp)
- "Pass BODY to the octave process in SESSION. If RESULT-TYPE
-equals 'output then return the outputs of the statements in BODY,
-if RESULT-TYPE equals 'value then return the value of the last
-statement in BODY, as elisp."
+ "Pass BODY to the octave process in SESSION.
+If RESULT-TYPE equals 'output then return the outputs of the
+statements in BODY, if RESULT-TYPE equals 'value then return the
+value of the last statement in BODY, as elisp."
(if session
(org-babel-octave-evaluate-session session body result-type matlabp)
(org-babel-octave-evaluate-external-process body result-type matlabp)))
@@ -241,8 +241,9 @@ statement in BODY, as elisp."
(mapconcat #'identity (reverse results) "\n"))))))
(defun org-babel-octave-import-elisp-from-file (file-name)
- "Import data from FILE-NAME. This removes initial blank and
-comment lines and then calls `org-babel-import-elisp-from-file'."
+ "Import data from FILE-NAME.
+This removes initial blank and comment lines and then calls
+`org-babel-import-elisp-from-file'."
(let ((temp-file (make-temp-file "org-babel-results-")) beg end)
(with-temp-file temp-file
(insert-file-contents file-name)
diff --git a/lisp/ob-perl.el b/lisp/ob-perl.el
index 3749295..63ff675 100644
--- a/lisp/ob-perl.el
+++ b/lisp/ob-perl.el
@@ -50,8 +50,8 @@
vars "\n") "\n" (org-babel-trim body) "\n")))
(defun org-babel-execute:perl (body params)
- "Execute a block of Perl code with org-babel. This function is
-called by `org-babel-execute-src-block'."
+ "Execute a block of Perl code with Babel.
+This function is called by `org-babel-execute-src-block'."
(let* ((processed-params (org-babel-process-params params))
(session (nth 0 processed-params))
(vars (nth 1 processed-params))
@@ -68,13 +68,14 @@ called by `org-babel-execute-src-block'."
(nth 5 processed-params) (cdr (assoc :rownames params))))))
(defun org-babel-prep-session:perl (session params)
- "Prepare SESSION according to the header arguments specified in PARAMS."
+ "Prepare SESSION according to the header arguments in PARAMS."
(error "Sessions are not supported for Perl."))
;; helper functions
(defun org-babel-perl-var-to-perl (var)
- "Convert an elisp var into a string of perl source code
+ "Convert an elisp value to a perl variable.
+The elisp value, VAR, is converted to a string of perl source code
specifying a var of the same value."
(if (listp var)
(concat "[" (mapconcat #'org-babel-perl-var-to-perl var ", ") "]")
@@ -83,7 +84,7 @@ specifying a var of the same value."
(defvar org-babel-perl-buffers '(:default . nil))
(defun org-babel-perl-initiate-session (&optional session params)
- "Simply return nil, as sessions are not supported by perl"
+ "Return nil because sessions are not supported by perl"
nil)
(defvar org-babel-perl-wrapper-method
@@ -99,10 +100,10 @@ print o join(\"\\n\", @r), \"\\n\"")
nil)
(defun org-babel-perl-evaluate (session body &optional result-type)
- "Pass BODY to the Perl process in SESSION. If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY, as elisp."
+ "Pass BODY to the Perl process in SESSION.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY, as elisp."
(when session (error "Sessions are not supported for Perl."))
(case result-type
(output (org-babel-eval org-babel-perl-command body))
diff --git a/lisp/ob-python.el b/lisp/ob-python.el
index d8fd758..8d2a3b4 100644
--- a/lisp/ob-python.el
+++ b/lisp/ob-python.el
@@ -42,7 +42,7 @@
(defvar org-babel-default-header-args:python '())
(defvar org-babel-python-command "python"
- "Name of command to use for executing python code.")
+ "Name of command for executing python code.")
(defvar org-babel-python-mode (if (featurep 'xemacs) 'python-mode 'python)
"Preferred python mode for use in running python interactively.")
@@ -59,8 +59,8 @@
"\n" (org-babel-trim body) "\n"))
(defun org-babel-execute:python (body params)
- "Execute a block of Python code with org-babel. This function is
-called by `org-babel-execute-src-block'."
+ "Execute a block of Python code with Babel.
+This function is called by `org-babel-execute-src-block'."
(let* ((processed-params (org-babel-process-params params))
(session (org-babel-python-initiate-session (first processed-params)))
(result-params (nth 2 processed-params))
@@ -78,7 +78,7 @@ called by `org-babel-execute-src-block'."
(cdr (assoc :rownames params)))))))
(defun org-babel-prep-session:python (session params)
- "Prepare SESSION according to the header arguments specified in PARAMS."
+ "Prepare SESSION according to the header arguments in PARAMS."
(let* ((session (org-babel-python-initiate-session session))
(vars (org-babel-ref-variables params))
(var-lines (mapcar ;; define any variables
@@ -105,14 +105,16 @@ called by `org-babel-execute-src-block'."
;; helper functions
(defun org-babel-python-var-to-python (var)
- "Convert an elisp var into a string of python source code
-specifying a var of the same value."
+ "Convert an elisp value to a python variable.
+Convert an elisp value, VAR, into a string of python source code
+specifying a variable of the same value."
(if (listp var)
(concat "[" (mapconcat #'org-babel-python-var-to-python var ", ") "]")
(if (equal var 'hline) "None" (format "%S" var))))
(defun org-babel-python-table-or-string (results)
- "If the results look like a list or tuple, then convert them into an
+ "Convert RESULTS into an appropriate elisp value.
+If the results look like a list or tuple, then convert them into an
Emacs-lisp table, otherwise return the results as a string."
((lambda (res)
(if (listp res)
@@ -137,7 +139,8 @@ Emacs-lisp table, otherwise return the results as a string."
(cdr (assoc session org-babel-python-buffers)))
(defun org-babel-python-initiate-session-by-key (&optional session)
- "If there is not a current inferior-process-buffer in SESSION
+ "Initiate a python session.
+If there is not a current inferior-process-buffer in SESSION
then create. Return the initialized session."
(require org-babel-python-mode)
(save-window-excursion
@@ -172,7 +175,7 @@ then create. Return the initialized session."
(org-babel-python-initiate-session-by-key session))))
(defvar org-babel-python-eoe-indicator "'org_babel_python_eoe'"
- "Used to indicate that evaluation is has completed.")
+ "A string to indicate that evaluation has completed.")
(defvar org-babel-python-wrapper-method
"
def main():
@@ -189,10 +192,10 @@ open('%s', 'w').write( pprint.pformat(main()) )")
(defun org-babel-python-evaluate
(buffer body &optional result-type result-params)
- "Pass BODY to the Python process in BUFFER. If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY, as elisp."
+ "Pass BODY to the Python process in BUFFER.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY, as elisp."
(if (not buffer)
;; external process evaluation
(case result-type
diff --git a/lisp/ob-ref.el b/lisp/ob-ref.el
index a7f5af9..148dafb 100644
--- a/lisp/ob-ref.el
+++ b/lisp/ob-ref.el
@@ -57,8 +57,9 @@
(declare-function org-at-table-p "org" (&optional table-type))
(defun org-babel-ref-variables (params)
- "Takes a parameter alist, and return an alist of variable
-names, and the emacs-lisp representation of the related value."
+ "Convert PARAMS to variable names and values.
+Takes a parameter alist, and return an alist of variable names,
+and the emacs-lisp representation of the related value."
(let ((assignments
(delq nil (mapcar (lambda (pair) (if (eq (car pair) :var) (cdr pair))) params)))
(others
@@ -69,13 +70,14 @@ names, and the emacs-lisp representation of the related value."
"[ \f\t\n\r\v]*\\(.+?\\)[ \f\t\n\r\v]*=[ \f\t\n\r\v]*\\(.+\\)[ \f\t\n\r\v]*")
(defun org-babel-ref-parse (assignment &optional params)
- "Parse a variable ASSIGNMENT in a header argument. If the
-right hand side of the assignment has a literal value return that
-value, otherwise interpret as a reference to an external resource
-and find it's value using `org-babel-ref-resolve-reference'.
-Return a list with two elements. The first element of the list
-will be the name of the variable, and the second will be an
-emacs-lisp representation of the value of the variable."
+ "Parse a variable ASSIGNMENT in a header argument.
+If the right hand side of the assignment has a literal value
+return that value, otherwise interpret as a reference to an
+external resource and find it's value using
+`org-babel-ref-resolve-reference'. Return a list with two
+elements. The first element of the list will be the name of the
+variable, and the second will be an emacs-lisp representation of
+the value of the variable."
(if (string-match org-babel-ref-split-regexp assignment)
(let ((var (match-string 1 assignment))
(ref (match-string 2 assignment)))
@@ -86,7 +88,8 @@ emacs-lisp representation of the value of the variable."
val)) (org-babel-ref-literal ref))))))
(defun org-babel-ref-literal (ref)
- "Determine if the right side of a header argument variable
+ "Return the value of REF if it is a literal value.
+Determine if the right side of a header argument variable
assignment is a literal value or is a reference to some external
resource. REF should be a string of the right hand side of the
assignment. If REF is literal then return it's value, otherwise
@@ -173,11 +176,11 @@ return nil."
result))))))
(defun org-babel-ref-index-list (index lis)
- "Return the subset of LIS indexed by INDEX. If INDEX is
-separated by ,s then each PORTION is assumed to index into the
-next deepest nesting or dimension. A valid PORTION can consist
-of either an integer index, or two integers separated by a : in
-which case the entire range is returned."
+ "Return the subset of LIS indexed by INDEX.
+If INDEX is separated by ,s then each PORTION is assumed to index
+into the next deepest nesting or dimension. A valid PORTION can
+consist of either an integer index, or two integers separated by
+a : in which case the entire range is returned."
(if (string-match "^,?\\([^,]+\\)" index)
(let ((length (length lis))
(portion (match-string 1 index))
@@ -218,9 +221,9 @@ which case the entire range is returned."
(defvar org-bracket-link-regexp)
(defun org-babel-ref-at-ref-p ()
- "Return the type of reference located at point or nil if none
-of the supported reference types are found. Supported reference
-types are tables and source blocks."
+ "Return the type of reference located at point.
+Return nil if none of the supported reference types are found.
+Supported reference types are tables and source blocks."
(cond ((org-at-table-p) 'table)
((looking-at "^[ \t]*#\\+BEGIN_SRC") 'source-block)
((looking-at org-bracket-link-regexp) 'file)
diff --git a/lisp/ob-ruby.el b/lisp/ob-ruby.el
index ef2ad46..869cb7c 100644
--- a/lisp/ob-ruby.el
+++ b/lisp/ob-ruby.el
@@ -65,8 +65,8 @@
vars "\n") "\n" body "\n")))
(defun org-babel-execute:ruby (body params)
- "Execute a block of Ruby code with org-babel. This function is
-called by `org-babel-execute-src-block'."
+ "Execute a block of Ruby code with Babel.
+This function is called by `org-babel-execute-src-block'."
(let* ((processed-params (org-babel-process-params params))
(session (org-babel-ruby-initiate-session (first processed-params)))
(result-params (nth 2 processed-params))
@@ -114,14 +114,16 @@ called by `org-babel-execute-src-block'."
;; helper functions
(defun org-babel-ruby-var-to-ruby (var)
- "Convert an elisp var into a string of ruby source code
-specifying a var of the same value."
+ "Convert VAR into a ruby variable.
+Convert an elisp value into a string of ruby source code
+specifying a variable of the same value."
(if (listp var)
(concat "[" (mapconcat #'org-babel-ruby-var-to-ruby var ", ") "]")
(format "%S" var)))
(defun org-babel-ruby-table-or-string (results)
- "If RESULTS look like a table, then convert them into an
+ "Convert RESULTS into an appropriate elisp value.
+If RESULTS look like a table, then convert them into an
Emacs-lisp table, otherwise return the results as a string."
(org-babel-read
(if (and (stringp results) (string-match "^\\[.+\\]$" results))
@@ -135,7 +137,8 @@ Emacs-lisp table, otherwise return the results as a string."
results)))
(defun org-babel-ruby-initiate-session (&optional session params)
- "If there is not a current inferior-process-buffer in SESSION
+ "Initiate a ruby session.
+If there is not a current inferior-process-buffer in SESSION
then create one. Return the initialized session."
(require 'inf-ruby)
(unless (string= session "none")
@@ -147,7 +150,7 @@ then create one. Return the initialized session."
(org-babel-ruby-initiate-session session)))))
(defvar org-babel-ruby-eoe-indicator ":org_babel_ruby_eoe"
- "Used to indicate that evaluation is has completed.")
+ "String to indicate that evaluation has completed.")
(defvar org-babel-ruby-f-write
"File.open('%s','w'){|f| f.write((_.class == String) ? _ : _.inspect)}")
(defvar org-babel-ruby-pp-f-write
@@ -175,10 +178,10 @@ end
(defun org-babel-ruby-evaluate
(buffer body &optional result-type result-params)
- "Pass BODY to the Ruby process in BUFFER. If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY, as elisp."
+ "Pass BODY to the Ruby process in BUFFER.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY, as elisp."
(if (not buffer)
;; external process evaluation
(case result-type
diff --git a/lisp/ob-sass.el b/lisp/ob-sass.el
index 78177ad..0099b44 100644
--- a/lisp/ob-sass.el
+++ b/lisp/ob-sass.el
@@ -47,8 +47,8 @@
"Expand BODY according to PARAMS, return the expanded body." body)
(defun org-babel-execute:sass (body params)
- "Execute a block of Sass code with org-babel. This function is
-called by `org-babel-execute-src-block'."
+ "Execute a block of Sass code with Babel.
+This function is called by `org-babel-execute-src-block'."
(let* ((result-params (split-string (or (cdr (assoc :results params)) "")))
(file (cdr (assoc :file params)))
(out-file (or file (make-temp-file "org-babel-sass-out")))
@@ -60,7 +60,7 @@ called by `org-babel-execute-src-block'."
(or file (with-temp-buffer (insert-file-contents out-file) (buffer-string)))))
(defun org-babel-prep-session:sass (session params)
- "This function does nothing as sass does not support sessions."
+ "Raise an error because sass does not support sessions."
(error "Sass does not support sessions"))
(provide 'ob-sass)
diff --git a/lisp/ob-screen.el b/lisp/ob-screen.el
index 58425a7..c847806 100644
--- a/lisp/ob-screen.el
+++ b/lisp/ob-screen.el
@@ -49,7 +49,7 @@ In case you want to use a different screen than one selected by your $PATH")
"Expand BODY according to PARAMS, return the expanded body." body)
(defun org-babel-execute:screen (body params)
- "Send a block of code via screen to a terminal using org-babel.
+ "Send a block of code via screen to a terminal using Babel.
\"default\" session is be used when none is specified."
(message "Sending source code block to interactive terminal session...")
(save-window-excursion
@@ -82,7 +82,7 @@ In case you want to use a different screen than one selected by your $PATH")
;; helper functions
(defun org-babel-screen-session-execute-string (session body)
- "If SESSION exist, send BODY to it."
+ "If SESSION exists, send BODY to it."
(let ((socket (org-babel-screen-session-socketname session)))
(when socket
(let ((tmpfile (org-babel-screen-session-write-temp-file session body)))
@@ -93,7 +93,7 @@ In case you want to use a different screen than one selected by your $PATH")
"paste z"))))))
(defun org-babel-screen-session-socketname (session)
- "Check if SESSION exist by parsing output of \"screen -ls\"."
+ "Check if SESSION exists by parsing output of \"screen -ls\"."
(let* ((screen-ls (shell-command-to-string "screen -ls"))
(sockets (delq
nil
@@ -125,8 +125,8 @@ In case you want to use a different screen than one selected by your $PATH")
tmpfile))
(defun org-babel-screen-test ()
- "Test if the default setup works. The terminal should shortly
-flicker."
+ "Test if the default setup works.
+The terminal should shortly flicker."
(interactive)
(let* ((session "org-babel-testing")
(random-string (format "%s" (random 99999)))
diff --git a/lisp/ob-sh.el b/lisp/ob-sh.el
index 5748171..f327d22 100644
--- a/lisp/ob-sh.el
+++ b/lisp/ob-sh.el
@@ -43,8 +43,8 @@
(defvar org-babel-default-header-args:sh '())
(defvar org-babel-sh-command "sh"
- "Command used to invoke a shell. This will be passed to
- `shell-command-on-region'")
+ "Command used to invoke a shell.
+This will be passed to `shell-command-on-region'")
(defun org-babel-expand-body:sh (body params &optional processed-params)
"Expand BODY according to PARAMS, return the expanded body."
@@ -59,8 +59,8 @@
vars "\n") "\n" body "\n\n")))
(defun org-babel-execute:sh (body params)
- "Execute a block of Shell commands with org-babel. This
-function is called by `org-babel-execute-src-block'."
+ "Execute a block of Shell commands with Babel.
+This function is called by `org-babel-execute-src-block'."
(let* ((processed-params (org-babel-process-params params))
(session (org-babel-sh-initiate-session (nth 0 processed-params)))
(result-params (nth 2 processed-params))
@@ -102,8 +102,9 @@ function is called by `org-babel-execute-src-block'."
;; helper functions
(defun org-babel-sh-var-to-sh (var &optional sep)
- "Convert an elisp var into a string of shell commands
-specifying a var of the same value."
+ "Convert an elisp value to a shell variable.
+Convert an elisp var into a string of shell commands specifying a
+var of the same value."
(if (listp var)
(flet ((deep-string (el)
(if (listp el)
@@ -115,7 +116,8 @@ specifying a var of the same value."
(if (stringp var) (format "%s" var) (format "%S" var))))
(defun org-babel-sh-table-or-results (results)
- "If the results look like a table, then convert them into an
+ "Convert RESULTS to an appropriate elisp value.
+If the results look like a table, then convert them into an
Emacs-lisp table, otherwise return the results as a string."
(org-babel-read
(if (string-match "^\\[.+\\]$" results)
@@ -136,15 +138,15 @@ Emacs-lisp table, otherwise return the results as a string."
(progn (shell session) (get-buffer (current-buffer)))))))
(defvar org-babel-sh-eoe-indicator "echo 'org_babel_sh_eoe'"
- "Used to indicate that evaluation is has completed.")
+ "String to indicate that evaluation has completed.")
(defvar org-babel-sh-eoe-output "org_babel_sh_eoe"
- "Used to indicate that evaluation is has completed.")
+ "String to indicate that evaluation has completed.")
(defun org-babel-sh-evaluate (session body &optional result-params)
- "Pass BODY to the Shell process in BUFFER. If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY."
+ "Pass BODY to the Shell process in BUFFER.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY."
((lambda (results)
(if (or (member "scalar" result-params)
(member "output" result-params))
diff --git a/lisp/ob-sql.el b/lisp/ob-sql.el
index 634c5af..8f72f53 100644
--- a/lisp/ob-sql.el
+++ b/lisp/ob-sql.el
@@ -54,8 +54,8 @@
"Expand BODY according to PARAMS, return the expanded body." body)
(defun org-babel-execute:sql (body params)
- "Execute a block of Sql code with org-babel. This function is
-called by `org-babel-execute-src-block'."
+ "Execute a block of Sql code with Babel.
+This function is called by `org-babel-execute-src-block'."
(let* ((result-params (split-string (or (cdr (assoc :results params)) "")))
(processed-params (org-babel-process-params params))
(cmdline (cdr (assoc :cmdline params)))
@@ -80,7 +80,7 @@ called by `org-babel-execute-src-block'."
(defun org-babel-prep-session:sql (session params)
- "Prepare SESSION according to the header arguments specified in PARAMS."
+ "Raise an error because Sql sessions aren't implemented."
(error "sql sessions not yet implemented"))
(provide 'ob-sql)
diff --git a/lisp/ob-sqlite.el b/lisp/ob-sqlite.el
index 0f01bc8..252bec1 100644
--- a/lisp/ob-sqlite.el
+++ b/lisp/ob-sqlite.el
@@ -48,8 +48,8 @@
(defvar org-babel-sqlite3-command "sqlite3")
(defun org-babel-execute:sqlite (body params)
- "Execute a block of Sqlite code with org-babel. This function is
-called by `org-babel-execute-src-block'."
+ "Execute a block of Sqlite code with Babel.
+This function is called by `org-babel-execute-src-block'."
(let ((result-params (split-string (or (cdr (assoc :results params)) "")))
(vars (org-babel-ref-variables params))
(db (cdr (assoc :db params)))
@@ -141,7 +141,8 @@ called by `org-babel-execute-src-block'."
table))
(defun org-babel-prep-session:sqlite (session params)
- "Prepare SESSION according to the header arguments specified in PARAMS."
+ "Raise an error because support for sqlite sessions isn't implemented.
+Prepare SESSION according to the header arguments specified in PARAMS."
(error "sqlite sessions not yet implemented"))
(provide 'ob-sqlite)
diff --git a/lisp/ob-table.el b/lisp/ob-table.el
index 37ee327..63d7e65 100644
--- a/lisp/ob-table.el
+++ b/lisp/ob-table.el
@@ -54,15 +54,16 @@
(require 'ob)
(defun org-babel-table-truncate-at-newline (string)
- "If STRING ends in a newline character, then remove the newline
+ "Replace newline character with ellipses.
+If STRING ends in a newline character, then remove the newline
character and replace it with ellipses."
(if (and (stringp string) (string-match "[\n\r]" string))
(concat (substring string 0 (match-beginning 0)) "...")
string))
(defmacro sbe (source-block &rest variables)
- "Return the results of calling SOURCE-BLOCK assigning every
-variable in VARIABLES. Each element of VARIABLES should be a two
+ "Return the results of calling SOURCE-BLOCK with VARIABLES.
+Each element of VARIABLES should be a two
element list, whose first element is the name of the variable and
second element is a string of its value. The following call to
`sbe' would be equivalent to the following source code block.
diff --git a/lisp/ob-tangle.el b/lisp/ob-tangle.el
index 60fe114..19b1840 100644
--- a/lisp/ob-tangle.el
+++ b/lisp/ob-tangle.el
@@ -56,10 +56,10 @@ then the name of the language is used."
;;;###autoload
(defun org-babel-load-file (file)
- "Load the contents of the Emacs Lisp source code blocks in the
-org-mode formatted FILE. This function will first export the
-source code using `org-babel-tangle' and then load the resulting
-file using `load-file'."
+ "Load Emacs Lisp source code blocks in the Org-mode FILE.
+This function exports the source code using
+`org-babel-tangle' and then loads the resulting file using
+`load-file'."
(flet ((age (file)
(float-time
(time-subtract (current-time)
@@ -76,11 +76,11 @@ file using `load-file'."
;;;###autoload
(defun org-babel-tangle-file (file &optional target-file lang)
- "Extract the bodies of all source code blocks in FILE with
-`org-babel-tangle'. Optional argument TARGET-FILE can be used to
-specify a default export file for all source blocks. Optional
-argument LANG can be used to limit the exported source code
-blocks by language."
+ "Extract the bodies of source code blocks in FILE.
+Source code blocks are extracted with `org-babel-tangle'.
+Optional argument TARGET-FILE can be used to specify a default
+export file for all source blocks. Optional argument LANG can be
+used to limit the exported source code blocks by language."
(interactive "fFile to tangle: \nP")
(let ((visited-p (get-file-buffer (expand-file-name file)))
to-be-removed)
@@ -97,7 +97,8 @@ blocks by language."
;;;###autoload
(defun org-babel-tangle (&optional target-file lang)
- "Extract the bodies of all source code blocks from the current
+ "Write code blocks to source-specific files.
+Extract the bodies of all source code blocks from the current
file into their own source-specific files. Optional argument
TARGET-FILE can be used to specify a default export file for all
source blocks. Optional argument LANG can be used to limit the
@@ -181,7 +182,8 @@ exported source code blocks by language."
path-collector)))
(defun org-babel-tangle-clean ()
- "Call this function inside of a source-code file generated by
+ "Remove comments inserted by `org-babel-tangle'.
+Call this function inside of a source-code file generated by
`org-babel-tangle' to remove all comments inserted automatically
by `org-babel-tangle'. Warning, this comment removes any lines
containing constructs which resemble org-mode file links or noweb
@@ -195,7 +197,7 @@ references."
(defvar org-stored-links)
(defun org-babel-tangle-collect-blocks (&optional lang)
- "Collect all source blocks in the current org-mode file.
+ "Collect source blocks in the current Org-mode file.
Return an association list of source-code block specifications of
the form used by `org-babel-spec-to-string' grouped by language.
Optional argument LANG can be used to limit the collected source
@@ -255,7 +257,8 @@ code blocks by language."
blocks))
(defun org-babel-spec-to-string (spec)
- "Insert the source-code specified by SPEC into the current
+ "Insert SPEC into the current file.
+Insert the source-code specified by SPEC into the current
source code file. This function uses `comment-region' which
assumes that the appropriate major-mode is set. SPEC has the
form
diff --git a/lisp/ob.el b/lisp/ob.el
index 9cdfb38..bc1c2c9 100644
--- a/lisp/ob.el
+++ b/lisp/ob.el
@@ -68,7 +68,8 @@
:group 'org)
(defcustom org-confirm-babel-evaluate t
- "Require confirmation before interactively evaluating code
+ "Confirm before evaluation.
+Require confirmation before interactively evaluating code
blocks in Org-mode buffers. The default value of this variable
is t, meaning confirmation is required for any code block
evaluation. This variable can be set to nil to inhibit any
@@ -90,8 +91,7 @@ remove code block execution from the C-c C-c keybinding."
(put 'org-confirm-babel-evaluate 'safe-local-variable (lambda (x) (eq x t)))
(defcustom org-babel-no-eval-on-ctrl-c-ctrl-c nil
- "This variable can be set to remove code block evaluation from
-the C-c C-c key binding."
+ "Remove code block evaluation from the C-c C-c key binding."
:group 'org-babel
:type 'boolean)
@@ -127,7 +127,7 @@ the C-c C-c key binding."
"Regexp used to identify inline src-blocks.")
(defun org-babel-get-src-block-info (&optional header-vars-only)
- "Get information of the current source block.
+ "Get information on the current source block.
Returns a list
(language body header-arguments-alist switches name function-args indent).
@@ -173,11 +173,11 @@ added to the header-arguments-alist."
nil))))
(defun org-babel-confirm-evaluate (info)
- "Confirm that the user wishes to evaluate the code block
-defined by INFO. This behavior can be suppressed by setting the
-value of `org-confirm-babel-evaluate' to nil, in which case all
-future interactive code block evaluations will proceed without
-any confirmation from the user.
+ "Confirm evaluation of the code block INFO.
+This behavior can be suppressed by setting the value of
+`org-confirm-babel-evaluate' to nil, in which case all future
+interactive code block evaluations will proceed without any
+confirmation from the user.
Note disabling confirmation may result in accidental evaluation
of potentially harmful code."
@@ -196,7 +196,8 @@ of potentially harmful code."
;;;###autoload
(defun org-babel-execute-src-block-maybe ()
- "Detect if this is context for a org-babel src-block and if so
+ "Conditionally execute a source block.
+Detect if this is context for a Babel src-block and if so
then run `org-babel-execute-src-block'."
(interactive)
(if (not org-babel-no-eval-on-ctrl-c-ctrl-c)
@@ -208,7 +209,8 @@ then run `org-babel-execute-src-block'."
;;;###autoload
(defun org-babel-expand-src-block-maybe ()
- "Detect if this is context for a org-babel src-block and if so
+ "Conditionally expand a source block.
+Detect if this is context for a org-babel src-block and if so
then run `org-babel-expand-src-block'."
(interactive)
(let ((info (org-babel-get-src-block-info)))
@@ -218,7 +220,8 @@ then run `org-babel-expand-src-block'."
;;;###autoload
(defun org-babel-load-in-session-maybe ()
- "Detect if this is context for a org-babel src-block and if so
+ "Conditionally load a source block in a session.
+Detect if this is context for a org-babel src-block and if so
then run `org-babel-load-in-session'."
(interactive)
(let ((info (org-babel-get-src-block-info)))
@@ -230,7 +233,8 @@ then run `org-babel-load-in-session'."
;;;###autoload
(defun org-babel-pop-to-session-maybe ()
- "Detect if this is context for a org-babel src-block and if so
+ "Conditionally pop to a session.
+Detect if this is context for a org-babel src-block and if so
then run `org-babel-pop-to-session'."
(interactive)
(let ((info (org-babel-get-src-block-info)))
@@ -241,9 +245,9 @@ then run `org-babel-pop-to-session'."
(defconst org-babel-header-arg-names
'(cache cmdline colnames dir exports file noweb results
session tangle var noeval comments)
- "Common header arguments used by org-babel. Note that
-individual languages may define their own language specific
-header arguments as well.")
+ "Common header arguments used by org-babel.
+Note that individual languages may define their own language
+specific header arguments as well.")
(defvar org-babel-default-header-args
'((:session . "none") (:results . "replace") (:exports . "code")
@@ -259,23 +263,25 @@ header arguments as well.")
(defvar org-babel-result-regexp
"^[ \t]*#\\+res\\(ults\\|name\\)\\(\\[\\([[:alnum:]]+\\)\\]\\)?\\:[ \t]*"
- "Regular expression used to match result lines. If the
-results are associated with a hash key then the hash will be
-saved in the second match data.")
+ "Regular expression used to match result lines.
+If the results are associated with a hash key then the hash will
+be saved in the second match data.")
(defvar org-babel-result-w-name-regexp
(concat org-babel-result-regexp
"\\([^ ()\f\t\n\r\v]+\\)\\(\(\\(.*\\)\)\\|\\)"))
(defvar org-babel-min-lines-for-block-output 10
- "If number of lines of output is equal to or exceeds this
+ "The minimum number of lines for block output.
+If number of lines of output is equal to or exceeds this
value, the output is placed in a #+begin_example...#+end_example
block. Otherwise the output is marked as literal by inserting
colons at the starts of the lines. This variable only takes
effect if the :results output option is in effect.")
(defvar org-babel-noweb-error-langs nil
- "List of language for which errors should be raised when the
+ "Languages for which Babel will raise literate programming errors.
+List of languages for which errors should be raised when the
source code block satisfying a noweb reference in this language
can not be resolved.")
@@ -293,10 +299,10 @@ can not be resolved.")
(defvar call-process-region)
;;;###autoload
(defun org-babel-execute-src-block (&optional arg info params)
- "Execute the current source code block, and insert the results
-into the buffer. Source code execution and the collection and
-formatting of results can be controlled through a variety of
-header arguments.
+ "Execute the current source code block.
+Insert the results of execution into the buffer. Source code
+execution and the collection and formatting of results can be
+controlled through a variety of header arguments.
Optionally supply a value for INFO in the form returned by
`org-babel-get-src-block-info'.
@@ -367,15 +373,17 @@ block."
(setq call-process-region 'org-babel-call-process-region-original))))
(defun org-babel-expand-body:generic (body params &optional processed-params)
- "Expand a block of code with org-babel according to it's header
+ "Expand BODY with PARAMS.
+Expand a block of code with org-babel according to it's header
arguments. This generic implementation of body expansion is
called for languages which have not defined their own specific
org-babel-expand-body:lang function." body)
;;;###autoload
(defun org-babel-expand-src-block (&optional arg info params)
- "Expand the current source code block according to it's header
-arguments, and pop open the results in a preview buffer."
+ "Expand the current source code block.
+Expand according to the source code block's header
+arguments and pop open the results in a preview buffer."
(interactive)
(let* ((info (or info (org-babel-get-src-block-info)))
(lang (nth 0 info))
@@ -395,9 +403,10 @@ arguments, and pop open the results in a preview buffer."
;;;###autoload
(defun org-babel-load-in-session (&optional arg info)
- "Load the body of the current source-code block. Evaluate the
-header arguments for the source block before entering the
-session. After loading the body this pops open the session."
+ "Load the body of the current source-code block.
+Evaluate the header arguments for the source block before
+entering the session. After loading the body this pops open the
+session."
(interactive)
(let* ((info (or info (org-babel-get-src-block-info)))
(lang (nth 0 info))
@@ -476,7 +485,8 @@ results already exist."
;;;###autoload
(defun org-babel-execute-buffer (&optional arg)
- "Call `org-babel-execute-src-block' on every source block in
+ "Execute source code blocks in a buffer.
+Call `org-babel-execute-src-block' on every source block in
the current buffer."
(interactive "P")
(save-excursion
@@ -491,7 +501,8 @@ the current buffer."
;;;###autoload
(defun org-babel-execute-subtree (&optional arg)
- "Call `org-babel-execute-src-block' on every source block in
+ "Execute source code blocks in a subtree.
+Call `org-babel-execute-src-block' on every source block in
the current subtree."
(interactive "P")
(save-restriction
@@ -512,15 +523,14 @@ the current subtree."
hash))
(defun org-babel-result-hash (&optional info)
- "Return the in-buffer hash associated with the results
-specified in INFO."
+ "Return the in-buffer hash associated with INFO."
(org-babel-where-is-src-block-result nil info)
(org-babel-clean-text-properties (match-string 3)))
(defun org-babel-hide-hash ()
- "Hide the hash in the current results line. Only the initial
-`org-babel-hash-show' characters of the hash will remain
-visible."
+ "Hide the hash in the current results line.
+Only the initial `org-babel-hash-show' characters of the hash
+will remain visible."
(add-to-invisibility-spec '(org-babel-hide-hash . t))
(save-excursion
(when (and (re-search-forward org-babel-result-regexp nil t)
@@ -536,10 +546,10 @@ visible."
(overlay-put ov1 'babel-hash hash)))))
(defun org-babel-hide-all-hashes ()
- "Hide the hash in the current buffer. Only the initial
-`org-babel-hash-show' characters of each hash will remain
-visible. This function should be called as part of the
-`org-mode-hook'."
+ "Hide the hash in the current buffer.
+Only the initial `org-babel-hash-show' characters of each hash
+will remain visible. This function should be called as part of
+the `org-mode-hook'."
(save-excursion
(while (re-search-forward org-babel-result-regexp nil t)
(goto-char (match-beginning 0))
@@ -548,9 +558,9 @@ visible. This function should be called as part of the
(add-hook 'org-mode-hook 'org-babel-hide-all-hashes)
(defun org-babel-hash-at-point (&optional point)
- "Return the value of the hash at `point'. The hash is also
-added as the last element of the kill ring. This can be called
-with C-c C-c."
+ "Return the value of the hash at POINT.
+The hash is also added as the last element of the kill ring.
+This can be called with C-c C-c."
(interactive)
(let ((hash (car (delq nil (mapcar
(lambda (ol) (overlay-get ol 'babel-hash))
@@ -559,7 +569,8 @@ with C-c C-c."
(add-hook 'org-ctrl-c-ctrl-c-hook 'org-babel-hash-at-point)
(defun org-babel-result-hide-spec ()
- "Add `org-babel-hide-result' as an invisibility spec for hiding
+ "Hide portions of results lines.
+Add `org-babel-hide-result' as an invisibility spec for hiding
portions of results lines."
(add-to-invisibility-spec '(org-babel-hide-result . t)))
(add-hook 'org-mode-hook 'org-babel-result-hide-spec)
@@ -655,7 +666,8 @@ portions of results lines."
(defvar org-file-properties)
(defun org-babel-params-from-properties (&optional lang)
- "Return an association list of any source block params which
+ "Retrieve parameters specified as properties.
+Return an association list of any source block params which
may be specified in the properties of the current outline entry."
(save-match-data
(let (val sym)
@@ -677,7 +689,8 @@ may be specified in the properties of the current outline entry."
(and (boundp sym) (eval sym))))))))))
(defun org-babel-params-from-buffer ()
- "Return an association list of any source block params which
+ "Retrieve per-buffer parameters.
+ Return an association list of any source block params which
may be specified at the top of the current buffer."
(or org-babel-current-buffer-properties
(setq org-babel-current-buffer-properties
@@ -693,8 +706,7 @@ may be specified at the top of the current buffer."
(defvar org-src-preserve-indentation)
(defun org-babel-parse-src-block-match ()
- "Parse the match data resulting from a match of the
-`org-babel-src-block-regexp'."
+ "Parse the results from a match of the `org-babel-src-block-regexp'."
(let* ((block-indentation (length (match-string 1)))
(lang (org-babel-clean-text-properties (match-string 2)))
(lang-headers (intern (concat "org-babel-default-header-args:" lang)))
@@ -720,8 +732,7 @@ may be specified at the top of the current buffer."
block-indentation)))
(defun org-babel-parse-inline-src-block-match ()
- "Parse the match data resulting from a match of the
-`org-babel-inline-src-block-regexp'."
+ "Parse the results from a match of the `org-babel-inline-src-block-regexp'."
(let* ((lang (org-babel-clean-text-properties (match-string 2)))
(lang-headers (intern (concat "org-babel-default-header-args:" lang))))
(list lang
@@ -776,7 +787,8 @@ Return a list (session vars result-params result-type colnames rownames)."
(remove 'hline table))
(defun org-babel-get-colnames (table)
- "Return a cons cell, the `car' of which contains the TABLE less
+ "Return the column names of TABLE.
+Return a cons cell, the `car' of which contains the TABLE less
colnames, and the `cdr' of which contains a list of the column
names."
(if (equal 'hline (nth 1 table))
@@ -784,7 +796,8 @@ names."
(cons (cdr table) (car table))))
(defun org-babel-get-rownames (table)
- "Return a cons cell, the `car' of which contains the TABLE less
+ "Return the row names of TABLE.
+Return a cons cell, the `car' of which contains the TABLE less
colnames, and the `cdr' of which contains a list of the column
names. Note: this function removes any hlines in TABLE."
(flet ((trans (table) (apply #'mapcar* #'list table)))
@@ -823,7 +836,8 @@ names. Note: this function removes any hlines in TABLE."
(cdr (car (last names)))))))
(defun org-babel-disassemble-tables (vars hlines colnames rownames)
- "Process the variables in VARS according to the HLINES,
+ "Parse tables for further processing.
+Process the variables in VARS according to the HLINES,
ROWNAMES and COLNAMES header arguments. Return a list consisting
of the vars, cnames and rnames."
(let (cnames rnames)
@@ -850,7 +864,8 @@ of the vars, cnames and rnames."
cnames rnames)))
(defun org-babel-reassemble-table (table colnames rownames)
- "Given a TABLE and set of COLNAMES and ROWNAMES add the names
+ "Add column and row names to a table.
+Given a TABLE and set of COLNAMES and ROWNAMES add the names
to the table for reinsertion to org-mode."
(if (listp table)
((lambda (table)
@@ -862,7 +877,8 @@ to the table for reinsertion to org-mode."
table))
(defun org-babel-where-is-src-block-head ()
- "Return the point at the beginning of the current source
+ "Find where the current source block begins.
+Return the point at the beginning of the current source
block. Specifically at the beginning of the #+BEGIN_SRC line.
If the point is not on a source block then return nil."
(let ((initial (point)) top bottom)
@@ -935,7 +951,8 @@ org-babel-named-src-block-regexp."
(message "result '%s' not found in this buffer" name))))
(defun org-babel-find-named-result (name)
- "Return the location of the result named NAME in the current
+ "Find a named result.
+Return the location of the result named NAME in the current
buffer or nil if no such result exists."
(save-excursion
(goto-char (point-min))
@@ -973,7 +990,8 @@ With optional prefix argument ARG, jump backward ARG many source blocks."
(defvar org-babel-lob-one-liner-regexp)
(defun org-babel-where-is-src-block-result (&optional insert info hash indent)
- "Return the point at the beginning of the result of the current
+ "Find where the current source block results begin.
+Return the point at the beginning of the result of the current
source block. Specifically at the beginning of the results line.
If no result exists for this block then create a results line
following the source block."
@@ -1076,8 +1094,9 @@ following the source block."
(defvar org-link-types-re)
(defun org-babel-read-link ()
- "Read the link at `point' into emacs-lisp. If the path of the
-link is a file path it is expanded using `expand-file-name'."
+ "Read the link at `point' into emacs-lisp.
+If the path of the link is a file path it is expanded using
+`expand-file-name'."
(let* ((case-fold-search t)
(raw (and (looking-at org-bracket-link-regexp)
(org-babel-clean-text-properties (match-string 1))))
@@ -1092,7 +1111,8 @@ link is a file path it is expanded using `expand-file-name'."
(defun org-babel-insert-result
(result &optional result-params info hash indent lang)
- "Insert RESULT into the current buffer after the end of the
+ "Insert RESULT into the current buffer.
+By default RESULT is inserted after the end of the
current source block. With optional argument RESULT-PARAMS
controls insertion of results in the org-mode file.
RESULT-PARAMS can take the following values...
@@ -1232,9 +1252,9 @@ code ---- the results are extracted in the syntax of the source
(point))))
(defun org-babel-result-to-file (result)
- "Convert RESULT into an `org-mode' link. If the
-`default-directory' is different from the containing file's
-directory then expand relative links."
+ "Convert RESULT into an `org-mode' link.
+If the `default-directory' is different from the containing
+file's directory then expand relative links."
(format
"[[file:%s]]"
(if (and default-directory
@@ -1266,9 +1286,9 @@ directory then expand relative links."
(insert "#+end_example\n"))))))
(defun org-babel-merge-params (&rest plists)
- "Combine all parameter association lists in PLISTS. Later
-elements of PLISTS override the values of previous element. This
-takes into account some special considerations for certain
+ "Combine all parameter association lists in PLISTS.
+Later elements of PLISTS override the values of previous element.
+This takes into account some special considerations for certain
parameters when merging lists."
(let ((results-exclusive-groups
'(("file" "vector" "table" "scalar" "raw" "org"
@@ -1367,10 +1387,10 @@ parameters when merging lists."
params)))))))))
(defun org-babel-expand-noweb-references (&optional info parent-buffer)
- "This function expands Noweb style references in the body of
-the current source-code block. For example the following
-reference would be replaced with the body of the source-code
-block named 'example-block'.
+ "Expand Noweb references in the body of the current source code block.
+
+For example the following reference would be replaced with the
+body of the source-code block named 'example-block'.
<<example-block>>
@@ -1484,8 +1504,8 @@ This is taken almost directly from `org-read-prop'."
(string-to-number string)))
(defun org-babel-import-elisp-from-file (file-name)
- "Read the results located at FILE-NAME into an elisp table. If
-the table is trivial, then return it as a scalar."
+ "Read the results located at FILE-NAME into an elisp table.
+If the table is trivial, then return it as a scalar."
(let (result)
(save-window-excursion
(with-temp-buffer
@@ -1517,8 +1537,8 @@ the table is trivial, then return it as a scalar."
(apply 'string (reverse (string-to-list string))))
(defun org-babel-chomp (string &optional regexp)
- "Remove any trailing space or carriage returns characters from
-STRING. Default regexp used is \"[ \f\t\n\r\v]\" but can be
+ "Strip trailing spaces and carriage returns from STRING.
+Default regexp used is \"[ \f\t\n\r\v]\" but can be
overwritten by specifying a regexp as a second argument."
(let ((regexp (or regexp "[ \f\t\n\r\v]")))
(while (and (> (length string) 0)
@@ -1527,7 +1547,8 @@ overwritten by specifying a regexp as a second argument."
string))
(defun org-babel-trim (string &optional regexp)
- "Like `org-babel-chomp' only it runs on both the front and back
+ "Strip leading and trailing spaces and carriage returns from STRING.
+Like `org-babel-chomp' only it runs on both the front and back
of the string."
(org-babel-chomp (org-babel-reverse-string
(org-babel-chomp (org-babel-reverse-string string) regexp))
@@ -1536,8 +1557,8 @@ of the string."
(defvar org-babel-org-babel-call-process-region-original nil)
(defun org-babel-tramp-handle-call-process-region
(start end program &optional delete buffer display &rest args)
- "Use tramp to handle call-process-region. Fixes a bug in
-`tramp-handle-call-process-region'."
+ "Use tramp to handle call-process-region.
+Fixes a bug in `tramp-handle-call-process-region'."
(if (and (featurep 'tramp) (file-remote-p default-directory))
(let ((tmpfile (tramp-compat-make-temp-file "")))
(write-region start end tmpfile)
@@ -1553,7 +1574,8 @@ of the string."
start end program delete buffer display args)))
(defun org-babel-maybe-remote-file (file)
- "If FILE specifies a remove file, then parse the information on
+ "Conditionally parse information on a remote connnection.
+If FILE specifies a remove file, then parse the information on
the remote connection."
(if (file-remote-p default-directory)
(let* ((vec (tramp-dissect-file-name default-directory))