Exporting source code blocks as LaTeX figures

Exporting source code blocks as LaTeX figures

[James Harkins]

Couple of questions about exporting LaTeX figures that are neither
tables nor images -- specifically, source code blocks using the
listings package.

1. Is there any way to use #+CAPTION with a #+BEGIN_figure block, so
that the caption will be rendered underneath the text in the figure?

It seems (from reading the org manual and some experimentation on my
own) that the answer is no. That's rather inconvenient; the journal
specifies that captions should appear below their respective figures,
but as it is:

#+CAPTION: Some code
#+NAME: code1
#+BEGIN_figure
#+BEGIN_SRC {}
// blah blah

-->

\begin{figure}
\caption{\label{code1}Some code}
\lstset{language={},numbers=none}
\begin{lstlisting}
// blah blah

-->

Figure 1. Some code.

// blah blah
.....

I can work around it by not using #+CAPTION, and writing
\caption{...}\label{...}. That shouldn't be a problem for this
project, unless for some reason I should have to re-export as, say,
ODT or HTML.

2. Is the customize variable "Org Latex Default Figure Position" only
used for tables and images? It would be nice if it applied to
BEGIN_figure as well (unless :options override that). "#+ATTR_LaTeX:
:options [htb]" is a mite inconvenient to replicate for every code
example. Certainly possible, but it would save a little effort if the
default were used here too.

hjh

Re: Exporting source code blocks as LaTeX figures

[Nicolas Goaziou]

Hello,

James Harkins <jamshark70@gmail.com> writes:

> Couple of questions about exporting LaTeX figures that are neither
> tables nor images -- specifically, source code blocks using the
> listings package.
>
> 1. Is there any way to use #+CAPTION with a #+BEGIN_figure block, so
> that the caption will be rendered underneath the text in the figure?
>
> It seems (from reading the org manual and some experimentation on my
> own) that the answer is no. That's rather inconvenient; the journal
> specifies that captions should appear below their respective figures,
> but as it is:
>
> #+CAPTION: Some code
> #+NAME: code1
> #+BEGIN_figure
> #+BEGIN_SRC {}
> // blah blah

Why don't you use:

  #+begin_figure
  #+caption: Some code
  #+name: code1
  #+begin_src {}
  // blah blah

instead? I.e., why don't you apply caption to src block? You can tweak
the position of the caption with "captionpos" option in listings
environment.

Caption are not supported in special blocks because these could contain
more than one object, and it wouldn't be clear which of them would have
the caption.

> 2. Is the customize variable "Org Latex Default Figure Position" only
> used for tables and images? It would be nice if it applied to
> BEGIN_figure as well (unless :options override that). "#+ATTR_LaTeX:
> :options [htb]" is a mite inconvenient to replicate for every code
> example. Certainly possible, but it would save a little effort if the
> default were used here too.

BEGIN_figure is a "special block", i.e. a generic environment. "[htb]"
does not always make sense in every environment.

Also, figure environment is created automatically in some cases (e.g.,
when `org-latex-listings' is nil and source block is captioned), so you
generally don't need to write it explicitly.

Anyway, you can easily add "[htb]" options to all figure environments in
the output with a filter.


Regards,

-- 
Nicolas Goaziou

Re: Exporting source code blocks as LaTeX figures

[James Harkins]

On Sat, May 18, 2013 at 3:39 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> instead? I.e., why don't you apply caption to src block? You can tweak
> the position of the caption with "captionpos" option in listings
> environment.

Wow, I hadn't thought of that. Actually that works better in a lot of ways.

Then the next problem... I'm going to have some figures that need to
span two columns. According to [1], I should use \begin{figure*} ...
\end{figure*}. Is there a way to do that using a special block? (First
guess, "#+BEGIN_figure*" causes the special block not to be
recognized.) Or do I need to write the literal LaTeX code for that?

hjh

[1] http://en.wikibooks.org/wiki/LaTeX/Floats,_Figures_and_Captions#Wide_figures_in_two_column_documents

Re: Exporting source code blocks as LaTeX figures

[Thomas S. Dye]

Aloha James,

James Harkins <jamshark70@gmail.com> writes:

> On Sat, May 18, 2013 at 3:39 PM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
>> instead? I.e., why don't you apply caption to src block? You can tweak
>> the position of the caption with "captionpos" option in listings
>> environment.
>
> Wow, I hadn't thought of that. Actually that works better in a lot of ways.
>
> Then the next problem... I'm going to have some figures that need to
> span two columns. According to [1], I should use \begin{figure*} ...
> \end{figure*}. Is there a way to do that using a special block? (First
> guess, "#+BEGIN_figure*" causes the special block not to be
> recognized.) Or do I need to write the literal LaTeX code for that?
>

No, you don't need to write literal LaTeX code. See Section 12.7.4 of
the manual, which describes setting the :float attribute to
'multicolumn'.

hth,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: Exporting source code blocks as LaTeX figures

[James Harkins]

On Mon, May 20, 2013 at 2:30 PM, Thomas S. Dye <tsd@tsdye.com> wrote:
>> Then the next problem... I'm going to have some figures that need to
>> span two columns. According to [1], I should use \begin{figure*} ...
>> \end{figure*}. Is there a way to do that using a special block? (First
>> guess, "#+BEGIN_figure*" causes the special block not to be
>> recognized.) Or do I need to write the literal LaTeX code for that?
>
> No, you don't need to write literal LaTeX code. See Section 12.7.4 of
> the manual, which describes setting the :float attribute to
> 'multicolumn'.

That section of the manual seems to describe the behavior for images. I did try:

#+ATTR_LaTeX: :multicolumn :options [htb]
#+BEGIN_figure
...
#+END_figure

... and :multicolumn had no effect on the output LaTeX code (either
with or without the preceding ":" -- I tried both):

\begin{figure}[htb]
\lstset{language={},label=code1,caption={Some code},numbers=none}
\begin{lstlisting}
// SuperCollider code here
.....
\end{lstlisting}
\end{figure}

Nor does this make a difference:

#+ATTR_LaTeX: :float multicolumn :options [htb]
#+BEGIN_figure

And if I omit BEGIN_figure altogether, and try to apply :float
directly to the source code block, then the floating environment
doesn't appear in the LaTeX code at all.

The other reference to multicolumn is for table export, and this isn't
a table either. So I think, as currently designed, :multicolumn simply
doesn't apply.

I'm aware that BEGIN_figure delimits a "special block" which
translates into LaTeX as an arbitrary environment, and not all
environments can be floated safely... but perhaps one approach for the
future would be to consider BEGIN_figure to be an extra-special
"special block" where we know that the properties of LaTeX floating
bodies are valid.

Or relax the restriction so that BEGIN_figure* no longer tries to
treat _ as a subscript marker.

hjh

Re: Exporting source code blocks as LaTeX figures

[Nicolas Goaziou]

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

Hello,

James Harkins <jamshark70@gmail.com> writes:

> The other reference to multicolumn is for table export, and this isn't
> a table either. So I think, as currently designed, :multicolumn simply
> doesn't apply.

Correct. The first attached patch implements :float multicolumn
and :float figure handling for source blocks. Would you mind to test it?

> I'm aware that BEGIN_figure delimits a "special block" which
> translates into LaTeX as an arbitrary environment, and not all
> environments can be floated safely... but perhaps one approach for the
> future would be to consider BEGIN_figure to be an extra-special
> "special block" where we know that the properties of LaTeX floating
> bodies are valid.

The second patch introduces :starred attribute for special blocks in
latex back-end, e.g.,

  #+attr_latex: :starred t :options [b]
  #+begin_figure
  something
  #+end_figure

I think it could be useful. Do you?


Regards,

-- 
Nicolas Goaziou

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

From cbc4a3a0b98cab9455bd7d3bd8b0ea8bfe8ea34e 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: Implement :float attribute for source blocks

* lisp/ox-latex.el (org-latex-src-block): Handle :float attribute. Its
  value can be set to "figure", "multicolumn" or "nil".

This needs to be documented in Org manual.
---
 lisp/ox-latex.el | 142 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 80 insertions(+), 62 deletions(-)

diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 41cf1d0..669c84b 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -2073,21 +2073,27 @@ 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))
+	   (long-listing (if (plist-member attributes :long-listing)
+			     (plist-get attributes :long-listing)
+			   org-latex-long-listings))
+	   (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 (long-listing "%s")
+		      ((string= "multicolumn" float)
+		       (format "\\begin{figure*}[%s]\n%s%%s\n\\end{figure*}"
+			       org-latex-default-figure-position
+			       caption-str))
+		      ((or label caption (string= "figure" 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 +2103,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 (long-listing "%s")
+		      ((string= "multicolumn" float)
+		       (format "\\begin{listing*}\n%%s\n%s\\end{listing*}"
+			       caption-str))
+		      ((or label caption (string= "figure" 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 +2164,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
+	       ((string= "multicolumn" float) '(("float" "*")))
+	       ((and (string= "figure" 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}"
-- 
1.8.2.3


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-ox-latex-Implement-starred-attribute-for-special-blo.patch --]
[-- Type: text/x-patch, Size: 1613 bytes --]

From 814edb94ffc45c0d1734e42805d8ede33ad81f67 Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <n.goaziou@gmail.com>
Date: Mon, 20 May 2013 10:44:44 +0200
Subject: [PATCH 2/2] ox-latex: Implement :starred attribute for special blocks

* lisp/ox-latex.el (org-latex-special-block): Implement :starred
  attribute for special blocks.
---
 lisp/ox-latex.el | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 669c84b..ab5c062 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -2045,15 +2045,17 @@ holding contextual information."
   "Transcode a SPECIAL-BLOCK element from Org to LaTeX.
 CONTENTS holds the contents of the block.  INFO is a plist
 holding contextual information."
-  (let ((type (downcase (org-element-property :type special-block)))
-	(opt (org-export-read-attribute :attr_latex special-block :options)))
-    (concat (format "\\begin{%s}%s\n" type (or opt ""))
+  (let* ((type (downcase (org-element-property :type special-block)))
+	 (attributes (org-export-read-attribute :attr_latex special-block))
+	 (opt (plist-get attributes :options))
+	 (starredp (plist-get attributes :starred)))
+    (concat (format "\\begin{%s%s}%s\n" type (if starredp "*" "") (or opt ""))
 	    ;; Insert any label or caption within the block
 	    ;; (otherwise, a reference pointing to that element will
 	    ;; count the section instead).
 	    (org-latex--caption/label-string special-block info)
 	    contents
-	    (format "\\end{%s}" type))))
+	    (format "\\end{%s%s}" type (if starredp "*" "")))))
 
 
 ;;;; Src Block
-- 
1.8.2.3

Re: Exporting source code blocks as LaTeX figures

[James Harkins]

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

On May 20, 2013 4:54 PM, "Nicolas Goaziou" <n.goaziou@gmail.com> wrote:
>
> Hello,
>
> James Harkins <jamshark70@gmail.com> writes:
>
> > The other reference to multicolumn is for table export, and this isn't
> > a table either. So I think, as currently designed, :multicolumn simply
> > doesn't apply.
>
> Correct. The first attached patch implements :float multicolumn
> and :float figure handling for source blocks. Would you mind to test it?

Sure, I can try both... but not until later today or maybe tomorrow.

Thanks!
hjh

[-- Attachment #2: Type: text/html, Size: 781 bytes --]