* contrib/babel/library-of-babel.org: 2011-08-28 Thomas Dye <tsd@tsdye.com>

* Add booktabs-notes source block to the Library of Babel.  Minor
	edits to booktabs documentation.

contrib/babel/library-of-babel.org

@@ -194,18 +194,26 @@ plot(data)
 
 * Tables
 
-** LaTeX Table export
+** LaTeX Table Export
 
 *** booktabs
 
-This block can be used to wrap a table in the latex =booktabs=
-environment, it takes the following arguments -- all but the first two
-are optional.
+This source block can be used to wrap a table in the latex =booktabs=
+environment. The source block adds a =toprule= and =bottomrule= (so
+don't use =hline= at the top or bottom of the table).  The =hline=
+after the header is replaced with a =midrule=.
+
+Note that this function bypasses the Org-mode LaTeX exporter and calls
+=orgtbl-to-generic= to create the output table.  This means that the
+entries in the table are not translated from Org-mode to LaTeX.
+
+It takes the following arguments -- all but the first two are
+optional.
 
 | arg   | description                                |
 |-------+--------------------------------------------|
 | table | a reference to the table                   |
-| align | optional alignment string                  |
+| align | alignment string                           |
 | env   | optional environment, default to "tabular" |
 | width | optional width specification string        |
 
@@ -241,7 +249,7 @@ are optional.
               (to-tab table))))))
 #+end_src
 
-*** Longtable
+*** longtable
 
 This block can be used to wrap a table in the latex =longtable=
 environment, it takes the following arguments -- all but the first two
@@ -288,6 +296,60 @@ are optional.
                    (list :lend " \\\\" :sep " & " :hline hline)))))
 #+end_src
 
+
+*** booktabs-notes
+
+This source block builds on [[booktabs]].  It accepts two additional
+arguments, both of which are optional.
+
+#+tblname: arguments
+| arg    | description                                          |
+|--------+------------------------------------------------------|
+| notes  | an org-mode table with footnotes                     |
+| lspace | if non-nil, insert =addlinespace= after =bottomrule= |
+
+An example footnote to the =arguments= table specifies the column
+span. Note the use of LaTeX, rather than Org-mode, markup.
+
+#+tblname: arguments-notes
+| \multicolumn{2}{l}{This is a footnote to the \emph{arguments} table.} |
+
+#+srcname: booktabs-notes
+#+begin_src emacs-lisp :var table='((:head) hline (:body)) :var notes='() :var align='() :var env="tabular" :var width='() :var lspace='() :noweb yes :results latex
+  (flet ((to-tab (tab)
+                 (orgtbl-to-generic
+                  (mapcar (lambda (lis)
+                            (if (listp lis)
+                                (mapcar (lambda (el)
+                                          (if (stringp el)
+                                              el
+                                            (format "%S" el))) lis)
+                              lis)) tab)
+                  (list :lend " \\\\" :sep " & " :hline "\\hline"))))
+    (org-fill-template
+     "
+    \\begin{%env}%width%align
+    \\toprule
+    %table
+    \\bottomrule%spacer
+    %notes
+    \\end{%env}\n"
+     (list
+      (cons "env"       (or env "table"))
+      (cons "width"     (if width (format "{%s}" width) ""))
+      (cons "align"     (if align (format "{%s}" align) ""))
+      (cons "spacer"    (if lspace "\\addlinespace" ""))
+      (cons "table"
+            ;; only use \midrule if it looks like there are column headers
+            (if (equal 'hline (second table))
+                (concat (to-tab (list (first table)))
+                        "\n\\midrule\n"
+                        (to-tab (cddr table)))
+              (to-tab table)))
+      (cons "notes" (if notes (to-tab notes) ""))
+      )))
+#+end_src
+
 ** Elegant lisp for transposing a matrix.
 
 #+tblname: transpose-example