Re: [RFC] Extend :float attribute to src blocks and normalize syntax

[Nicolas Goaziou <n.goaziou@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 412 bytes --]

Carsten Dominik <carsten.dominik@gmail.com> writes:

> I guess I mean anything not meaningful.  That keeps with the ELisp
> tradition that anything non-nil is t.  THe only disadvantage I see that
> it will become harder to debug typos like :float sidewasytable
> but that is better than breaking many peoples working files.

Fair enough. Here is an updated version for the patch.


Regards,

-- 
Nicolas Goaziou

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-latex-Extend-float-attribute-to-source-blocks-and.patch --]
[-- Type: text/x-patch, Size: 11871 bytes --]

From 45565503dce50f0e563dd4386ca4b46f9eefe428 Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <n.goaziou@gmail.com>
Date: Mon, 20 May 2013 10:43:18 +0200
Subject: [PATCH 1/2] ox-latex: Extend :float attribute to source blocks and
 normalize its values

* lisp/ox-latex.el (org-latex-src-block): Handle :float attribute. Its
  value can be set to "t", "multicolumn" or "nil".  Also
  remove :long-listing attribute, which is now replaced with :float
  nil.
(org-latex--org-table): Replace :float table with :float t.
(org-latex--inline-image): Replace :float figure with :float t.
(org-latex-long-listings): Remove variable.
* doc/org.texi (@LaTeX{} specific attributes): Document new :float values.
---
 doc/org.texi     |  37 +++++++++----
 lisp/ox-latex.el | 163 ++++++++++++++++++++++++++++---------------------------
 2 files changed, 109 insertions(+), 91 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 290c671..408d00d 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -11597,10 +11597,11 @@ environment, like @code{tabularx}, @code{longtable}, @code{array},
 @code{tabu}, @code{bmatrix}@enddots{}  It defaults to
 @code{org-latex-default-table-environment} value.
 @item :float
+@itemx :placement
 Float environment for the table.  Possible values are @code{sidewaystable},
-@code{multicolumn} and @code{table}.  If unspecified, a table with a caption
-will have a @code{table} environment.  Moreover, @code{:placement} attribute
-can specify the positioning of the float.
+@code{multicolumn}, @code{t} and @code{nil}.  When unspecified, a table with
+a caption will have a @code{table} environment.  Moreover, @code{:placement}
+attribute can specify the positioning of the float.
 @item :align
 @itemx :font
 @itemx :width
@@ -11675,12 +11676,18 @@ without specifying caption by setting the @code{:float} attribute.  You may
 also set it to:
 @itemize @minus
 @item
-@code{wrap}: if you would like to let text flow around the image.  It will
-make the figure occupy the left half of the page.
+@code{t}: if you want to use the standard @samp{figure} environment.  It is
+used by default if you provide a caption to the image.
 @item
 @code{multicolumn}: if you wish to include an image which spans multiple
 columns in a page.  This will export the image wrapped in a @code{figure*}
 environment.
+@item
+@code{wrap}: if you would like to let text flow around the image.  It will
+make the figure occupy the left half of the page.
+@item
+@code{nil}: if you need to avoid any floating environment, even when
+a caption is provided.
 @end itemize
 @noindent
 To modify the placement option of any floating environment, set the
@@ -11711,13 +11718,23 @@ omitted).
 @subsubheading Source blocks in @LaTeX{} export
 @cindex source blocks, in @LaTeX{} export
 
-In addition to syntax defined in @ref{Literal examples}, names and
-captions (@pxref{Images and tables}), source blocks also accept a
-@code{:long-listing} attribute, which prevents the block from floating
-when non-@code{nil}.
+In addition to syntax defined in @ref{Literal examples}, names and captions
+(@pxref{Images and tables}), source blocks also accept a @code{:float}
+attribute.  You may set it to:
+@itemize @minus
+@item
+@code{t}: if you want to make the source block a float.  It is the default
+value when a caption is provided.
+@item
+@code{mulicolumn}: if you wish to include a source block which spans multiple
+colums in a page.
+@item
+@code{nil}: if you need to avoid any floating evironment, even when a caption
+is provided.  It is useful for source code that may not fit in a single page.
+@end itemize
 
 @example
-#+ATTR_LATEX: :long-listing t
+#+ATTR_LATEX: :float nil
 #+BEGIN_SRC emacs-lisp
 Code that may not fit in a single page.
 #+END_SRC
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 3a01693..ff0ca1d 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -738,20 +738,6 @@ options will be applied to blocks of all languages."
 	   (string :tag "Minted option name ")
 	   (string :tag "Minted option value"))))
 
-(defcustom org-latex-long-listings nil
-  "When non-nil no listing will be wrapped within a float.
-
-Removing floats may break some functionalities.  For example, it
-will be impossible to use cross-references to listings when using
-`minted' set-up when this variable is non-nil.
-
-This value can be locally ignored with \":long-listing t\" and
-\":long-listing nil\" LaTeX attributes."
-  :group 'org-export-latex
-  :version "24.4"
-  :package-version '(Org . "8.0")
-  :type 'boolean)
-
 (defvar org-latex-custom-lang-environments nil
   "Alist mapping languages to language-specific LaTeX environments.
 
@@ -1711,10 +1697,10 @@ used as a communication channel."
 	 ;; Retrieve latex attributes from the element around.
 	 (attr (org-export-read-attribute :attr_latex parent))
 	 (float (let ((float (plist-get attr :float)))
-		  (cond ((string= float "wrap") 'wrap)
+		  (cond ((and (not float) (plist-member attr :float)) nil)
+			((string= float "wrap") 'wrap)
 			((string= float "multicolumn") 'multicolumn)
-			((or (string= float "figure")
-			     (org-element-property :caption parent))
+			((or float (org-element-property :caption parent))
 			 'figure))))
 	 (placement
 	  (let ((place (plist-get attr :placement)))
@@ -2073,21 +2059,24 @@ contextual information."
 			(continued (org-export-get-loc src-block info))
 			(new 0)))
 	   (retain-labels (org-element-property :retain-labels src-block))
-	   (long-listing
-	    (let ((attr (org-export-read-attribute :attr_latex src-block)))
-	      (if (plist-member attr :long-listing)
-		  (plist-get attr :long-listing)
-		org-latex-long-listings))))
+	   (attributes (org-export-read-attribute :attr_latex src-block))
+	   (float (plist-get attributes :float)))
       (cond
        ;; Case 1.  No source fontification.
        ((not org-latex-listings)
 	(let* ((caption-str (org-latex--caption/label-string src-block info))
-	       (float-env (and (not long-listing)
-			       (or label caption)
-			       (format "\\begin{figure}[H]\n%s%%s\n\\end{figure}"
-				       caption-str))))
+	       (float-env
+		(cond ((and (not float) (plist-member attributes :float)) "%s")
+		      ((string= "multicolumn" float)
+		       (format "\\begin{figure*}[%s]\n%s%%s\n\\end{figure*}"
+			       org-latex-default-figure-position
+			       caption-str))
+		      ((or caption float)
+		       (format "\\begin{figure}[H]\n%s%%s\n\\end{figure}"
+			       caption-str))
+		      (t "%s"))))
 	  (format
-	   (or float-env "%s")
+	   float-env
 	   (concat (format "\\begin{verbatim}\n%s\\end{verbatim}"
 			   (org-export-format-code-default src-block info))))))
        ;; Case 2.  Custom environment.
@@ -2097,46 +2086,52 @@ contextual information."
 			   custom-env))
        ;; Case 3.  Use minted package.
        ((eq org-latex-listings 'minted)
-	(let ((float-env
-	       (and (not long-listing)
-		    (or label caption)
-		    (format "\\begin{listing}[H]\n%%s\n%s\\end{listing}"
-			    (org-latex--caption/label-string src-block info))))
-	      (body
-	       (format
-		"\\begin{minted}[%s]{%s}\n%s\\end{minted}"
-		;; Options.
-		(org-latex--make-option-string
-		 (if (or (not num-start)
-			 (assoc "linenos" org-latex-minted-options))
-		     org-latex-minted-options
-		   (append `(("linenos")
-			     ("firstnumber" ,(number-to-string (1+ num-start))))
-			   org-latex-minted-options)))
-		;; Language.
-		(or (cadr (assq (intern lang) org-latex-minted-langs)) lang)
-		;; Source code.
-		(let* ((code-info (org-export-unravel-code src-block))
-		       (max-width
-			(apply 'max
-			       (mapcar 'length
-				       (org-split-string (car code-info)
-							 "\n")))))
-		  (org-export-format-code
-		   (car code-info)
-		   (lambda (loc num ref)
-		     (concat
-		      loc
-		      (when ref
-			;; Ensure references are flushed to the right,
-			;; separated with 6 spaces from the widest line
-			;; of code.
-			(concat (make-string (+ (- max-width (length loc)) 6)
-					     ?\s)
-				(format "(%s)" ref)))))
-		   nil (and retain-labels (cdr code-info)))))))
+	(let* ((caption-str (org-latex--caption/label-string src-block info))
+	       (float-env
+		(cond ((and (not float) (plist-member attributes :float)) "%s")
+		      ((string= "multicolumn" float)
+		       (format "\\begin{listing*}\n%%s\n%s\\end{listing*}"
+			       caption-str))
+		      ((or caption float)
+		       (format "\\begin{listing}[H]\n%%s\n%s\\end{listing}"
+			       caption-str))
+		      (t "%s")))
+	       (body
+		(format
+		 "\\begin{minted}[%s]{%s}\n%s\\end{minted}"
+		 ;; Options.
+		 (org-latex--make-option-string
+		  (if (or (not num-start)
+			  (assoc "linenos" org-latex-minted-options))
+		      org-latex-minted-options
+		    (append
+		     `(("linenos")
+		       ("firstnumber" ,(number-to-string (1+ num-start))))
+		     org-latex-minted-options)))
+		 ;; Language.
+		 (or (cadr (assq (intern lang) org-latex-minted-langs)) lang)
+		 ;; Source code.
+		 (let* ((code-info (org-export-unravel-code src-block))
+			(max-width
+			 (apply 'max
+				(mapcar 'length
+					(org-split-string (car code-info)
+							  "\n")))))
+		   (org-export-format-code
+		    (car code-info)
+		    (lambda (loc num ref)
+		      (concat
+		       loc
+		       (when ref
+			 ;; Ensure references are flushed to the right,
+			 ;; separated with 6 spaces from the widest line
+			 ;; of code.
+			 (concat (make-string (+ (- max-width (length loc)) 6)
+					      ?\s)
+				 (format "(%s)" ref)))))
+		    nil (and retain-labels (cdr code-info)))))))
 	  ;; Return value.
-	  (if float-env (format float-env body) body)))
+	  (format float-env body)))
        ;; Case 4.  Use listings package.
        (t
 	(let ((lst-lang
@@ -2152,19 +2147,25 @@ contextual information."
 			     (org-export-data main info)))))))
 	  (concat
 	   ;; Options.
-	   (format "\\lstset{%s}\n"
-		   (org-latex--make-option-string
-		    (append
-		     org-latex-listings-options
-		     `(("language" ,lst-lang))
-		     (when label `(("label" ,label)))
-		     (when caption-str `(("caption" ,caption-str)))
-		     (cond ((assoc "numbers" org-latex-listings-options) nil)
-			   ((not num-start) '(("numbers" "none")))
-			   ((zerop num-start) '(("numbers" "left")))
-			   (t `(("numbers" "left")
-				("firstnumber"
-				 ,(number-to-string (1+ num-start)))))))))
+	   (format
+	    "\\lstset{%s}\n"
+	    (org-latex--make-option-string
+	     (append
+	      org-latex-listings-options
+	      (cond
+	       ((and (not float) (plist-member attributes :float)) nil)
+	       ((string= "multicolumn" float) '(("float" "*")))
+	       ((and float (not (assoc "float" org-latex-listings-options)))
+		`(("float" ,org-latex-default-figure-position))))
+	      `(("language" ,lst-lang))
+	      (when label `(("label" ,label)))
+	      (when caption-str `(("caption" ,caption-str)))
+	      (cond ((assoc "numbers" org-latex-listings-options) nil)
+		    ((not num-start) '(("numbers" "none")))
+		    ((zerop num-start) '(("numbers" "left")))
+		    (t `(("numbers" "left")
+			 ("firstnumber"
+			  ,(number-to-string (1+ num-start)))))))))
 	   ;; Source code.
 	   (format
 	    "\\begin{lstlisting}\n%s\\end{lstlisting}"
@@ -2374,10 +2375,10 @@ This function assumes TABLE has `org' as its `:type' property and
 	 (float-env (unless (member table-env '("longtable" "longtabu"))
 		      (let ((float (plist-get attr :float)))
 			(cond
+			 ((and (not float) (plist-member attr :float)) nil)
 			 ((string= float "sidewaystable") "sidewaystable")
 			 ((string= float "multicolumn") "table*")
-			 ((or (string= float "table")
-			      (org-element-property :caption table))
+			 ((or float (org-element-property :caption table))
 			  "table")))))
 	 ;; Extract others display options.
 	 (fontsize (let ((font (plist-get attr :font)))
-- 
1.8.3