[O] [RFC] [PATCH] ox-latex: support :float no with caption for minted listings

[Aaron Ecay]

* lisp/ox-latex.el (org-latex-src-block): Support :float no with
caption for minted.
(org-latex-listings): Edit docstring to describe this usecase.

This takes advantage of the caption package’s \captionof command,
which allows to insert a caption (with autogenerated number and
\ref-able label) without creating a floating environment.  One example
of where this is useful is in the case of a minted source code listing
that spans more than one page.  (Latex floats can’t be larger than a
page, generally speaking.)

I haven’t done much testing, but the documentation of the listings
package seems to indicate that it already handles this case without
any special arrangement by org.
---
 lisp/ox-latex.el | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index c14d6dc..e29c6d2 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -727,6 +727,26 @@ using customize, or with
   \(require 'ox-latex)
   \(add-to-list 'org-latex-packages-alist '(\"\" \"minted\"))

+You can have listings with a caption which nonetheless do not
+float.  This is useful in case the source code takes up more than
+a page, in which case trying to float it will also truncate it.
+To achieve this, you should specifying the following attributes
+on the source block:
+
+  #+caption: ...
+  #+attr_latex: :float no
+  #+begin_src
+    ...
+  #+end_src
+
+In this case, if you are using minted you must add the
+\"caption\" latex package to your document:
+
+  \(add-to-list 'org-latex-packages-alist '(\"\" \"caption\"))
+
+The listings package handles this case correctly with no
+additional packages.
+
 In addition, it is necessary to install pygments
 \(http://pygments.org), and to configure the variable
 `org-latex-pdf-process' so that the -shell-escape option is
@@ -2301,7 +2321,11 @@ contextual information."
        ((eq listings 'minted)
        (let* ((caption-str (org-latex--caption/label-string src-block info))
               (float-env
-               (cond ((and (not float) (plist-member attributes :float)) "%s")
+               (cond ((and (string= "no" float) caption)
+                      (format "%%s\n%s" (replace-regexp-in-string
+                                         "\\\\caption" "\\captionof{listing}"
+                                         caption-str t t)))
+                     ((string= "no" float) "%s")
                      ((string= "multicolumn" float)
                       (format "\\begin{listing*}\n%%s\n%s\\end{listing*}"
                               caption-str))
--
2.0.4