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

[Carsten Dominik <carsten.dominik@gmail.com>]

On 31.5.2013, at 17:37, Nicolas Goaziou <n.goaziou@gmail.com> wrote:

> Hello,
> 
> The following patch extends :float attribute to src blocks (so they are
> on par with tables and images). It also slightly changes syntax for this
> attribute:
> 
>  |        | Old           | New      |
>  |--------+---------------+----------|
>  | Tables | :float table  | :float t |
>  | Images | :float figure | :float t | 
> 
> With this patch :float attribute also accepts a nil value in all cases,
> preventing any floating mechanism, even if a caption is provided. In
> particular, it replaces :long-listing attribute for src blocks:
> 
>  |            | Old             | New        |
>  |------------+-----------------+------------|
>  | Src blocks | :long-listing t | :float nil |
> 
> Overall, it makes :float syntax a bit more regular, but it implies some
> gotchas.

Hi Nicolas,

I like the possibilities this opens, in particular to set a nil value.
We could be nice to users and interpret `table' and `figure' as t.
This is not clean, but nice... :)

- Carsten

> 
> WDYT?
> 
> 
> Regards,
> 
> -- 
> Nicolas Goaziou
> From 0bf638246d91e5d855836ceeb24b405b3688729f 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 | 162 ++++++++++++++++++++++++++++---------------------------
> 2 files changed, 110 insertions(+), 89 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..237378d 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,9 +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")
> +			((or (string= float t)
> 			     (org-element-property :caption parent))
> 			 'figure))))
> 	 (placement
> @@ -2073,21 +2060,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 (string= float t))
> +		       (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 +2087,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 (string= float t))
> +		       (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 +2148,26 @@ 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 (string= float t)
> +		     (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,9 +2377,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")
> +			 ((or (string= float t)
> 			      (org-element-property :caption table))
> 			  "table")))))
> 	 ;; Extract others display options.
> -- 
> 1.8.3
>