[bug][ox-latex] Captions in equations

[bug][ox-latex] Captions in equations

[Rasmus]

Hi,

This example produces invalid LaTeX code:

#+CAPTION: test
#+ATTR_LATEX: :mode math :environment pmatrix
| \alpha | \beta | \gamma |

Namely,

\begin{equation}
\caption{test text}
\mathbf{H}=\begin{pmatrix}
 \vdots & 0 & \vdots \\
 \vdots & H & \vdots \\
 \vdots & 0 & \vdots \\
\end{pmatrix}.
\end{equation}

But an equation cannot have a caption.

I'm not sure what the desired behavior is.  (i) To silently drop the
caption, (ii) to wrap the equation in some sort of float and give it a
caption; or (iii) to print the text sans the \caption{·}.

(iii) can be archived with math-prefix.  (ii) is a bit weird, but
could be archived relatively easy, but it's not really what one would
expect; it's consistent with how captions work for tables (turned into
a float when a caption is present).  (i) is also a bit weird, but
seems the most reasonable to me.

Since I don't know what the correct behavior is, I don't have a patch
right now.

–Rasmus

-- 
⠠⠵

Re: [bug][ox-latex] Captions in equations

[Vladimir Lomov]

Hello,
** Rasmus [2014-01-18 20:36:35 +0100]:

> Hi,

> This example produces invalid LaTeX code:

> #+CAPTION: test
> #+ATTR_LATEX: :mode math :environment pmatrix
> | \alpha | \beta | \gamma |

> Namely,

> \begin{equation}
> \caption{test text}
> \mathbf{H}=\begin{pmatrix}
>  \vdots & 0 & \vdots \\
>  \vdots & H & \vdots \\
>  \vdots & 0 & \vdots \\
> \end{pmatrix}.
> \end{equation}

> But an equation cannot have a caption.

> I'm not sure what the desired behavior is.  (i) To silently drop the
> caption, (ii) to wrap the equation in some sort of float and give it a
> caption; or (iii) to print the text sans the \caption{·}.

> (iii) can be archived with math-prefix.  (ii) is a bit weird, but
> could be archived relatively easy, but it's not really what one would
> expect; it's consistent with how captions work for tables (turned into
> a float when a caption is present).  (i) is also a bit weird, but
> seems the most reasonable to me.

> Since I don't know what the correct behavior is, I don't have a patch
> right now.

IMHO, this is wrong approach. I would consider this example as a special
way to generate a matrix when exporting to LaTeX, then CAPTION is
useless here. Also, HTML export will give differently looking result.

So, generally, question here is what the use-case to have special
transformation of a table for LaTeX export, providing that other export
backends never will do any special with given table (or will apply
different transformation), and to give a CAPTION to a table.

> –Rasmus

---
WBR, Vladimir Lomov

-- 
Fear is the greatest salesman.
		-- Robert Klein

Re: [bug][ox-latex] Captions in equations

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> This example produces invalid LaTeX code:
>
> #+CAPTION: test
> #+ATTR_LATEX: :mode math :environment pmatrix
> | \alpha | \beta | \gamma |
>
> Namely,
>
> \begin{equation}
> \caption{test text}
> \mathbf{H}=\begin{pmatrix}
>  \vdots & 0 & \vdots \\
>  \vdots & H & \vdots \\
>  \vdots & 0 & \vdots \\
> \end{pmatrix}.
> \end{equation}
>
> But an equation cannot have a caption.
>
> I'm not sure what the desired behavior is.  (i) To silently drop the
> caption, (ii) to wrap the equation in some sort of float and give it a
> caption; or (iii) to print the text sans the \caption{·}.
>
> (iii) can be archived with math-prefix.  (ii) is a bit weird, but
> could be archived relatively easy, but it's not really what one would
> expect; it's consistent with how captions work for tables (turned into
> a float when a caption is present).  (i) is also a bit weird, but
> seems the most reasonable to me.
>
> Since I don't know what the correct behavior is, I don't have a patch
> right now.

As a short term solution, I think the (i) is the best. That's exactly
what happens to LaTeX environments: in `org-latex-latex-environment',
the caption is dropped and only the label, if any, is inserted in the
environment.

As a long term solution, it would be interesting to be able to do (ii),
for both tables in math mode (but not in inline-math) and LaTeX
environments: captioning an equation is a reasonable request.


Regards,

-- 
Nicolas Goaziou

Re: [bug][ox-latex] Captions in equations

[Rasmus]

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

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Hello,
>
> Rasmus <rasmus@gmx.us> writes:
>
>> This example produces invalid LaTeX code:
>>
>> #+CAPTION: test
>> #+ATTR_LATEX: :mode math :environment pmatrix
>> | \alpha | \beta | \gamma |
>>
>> Namely,
>>
>> \begin{equation}
>> \caption{test text}
>> \mathbf{H}=\begin{pmatrix}
>>  \vdots & 0 & \vdots \\
>>  \vdots & H & \vdots \\
>>  \vdots & 0 & \vdots \\
>> \end{pmatrix}.
>> \end{equation}
>>
>> But an equation cannot have a caption.
>>
>> I'm not sure what the desired behavior is.  (i) To silently drop the
>> caption, (ii) to wrap the equation in some sort of float and give it a
>> caption; or (iii) to print the text sans the \caption{·}.
>>
>> (iii) can be archived with math-prefix.  (ii) is a bit weird, but
>> could be archived relatively easy, but it's not really what one would
>> expect; it's consistent with how captions work for tables (turned into
>> a float when a caption is present).  (i) is also a bit weird, but
>> seems the most reasonable to me.
>>
>> Since I don't know what the correct behavior is, I don't have a patch
>> right now.
>
> As a short term solution, I think the (i) is the best. That's exactly
> what happens to LaTeX environments: in `org-latex-latex-environment',
> the caption is dropped and only the label, if any, is inserted in the
> environment.

OK.  I can prepare a patch.

> As a long term solution, it would be interesting to be able to do (ii),
> for both tables in math mode (but not in inline-math) and LaTeX
> environments: captioning an equation is a reasonable request.

Indeed this seems long-term.

I have only rarely seen math-floats.  It is, however, sometimes used
in elsarticle.cls from the Elsevier publishing house.  See this
example:

    http://bayimg.com/aAHDfAAFE

Here the caption can be seen as the text below the equation, ("Where
Λ(·) is...")  and (16) is the reference.  The attached file play
around with some preliminary LaTeX styles for this.

In LaTeX the floating would be kind of odd, I think.  At the very
least math floats shouldn't be Figure or Tables (IMO); unfortunately
the Internets seem to suggest that you usually create additional
floats via packages such as newfloat of "caption".  HTML should also
be considered...

–Rasmus

--
This space is left intentionally blank

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: test.tex --]
[-- Type: text/x-tex, Size: 374 bytes --]

\documentclass[11pt]{article}
\usepackage{amsmath}
\begin{document}
first equation
\begin{equation}
  x=1
\end{equation}

Second equation
\par\noindent\fbox{\parbox{\textwidth}{
  \begin{equation}
    x=2\Lambda(x)
  \end{equation}
  Here, $\Lambda(\cdot)$ is \dots}}

\begin{figure}
  \fbox{\parbox{\textwidth}{\[g=3\]}}\caption{Third caption}
\end{figure}

\end{document}

Re: [bug][ox-latex] Captions in equations

[Rasmus]

Vladimir Lomov <lomov.vl@gmail.com> writes:

> Hello,
> ** Rasmus [2014-01-18 20:36:35 +0100]:
>
>> Hi,
>
>> This example produces invalid LaTeX code:
>
>> #+CAPTION: test
>> #+ATTR_LATEX: :mode math :environment pmatrix
>> | \alpha | \beta | \gamma |
>
>> Namely,
>
>> \begin{equation}
>> \caption{test text}
>> \mathbf{H}=\begin{pmatrix}
>>  \vdots & 0 & \vdots \\
>>  \vdots & H & \vdots \\
>>  \vdots & 0 & \vdots \\
>> \end{pmatrix}.
>> \end{equation}
>
>> But an equation cannot have a caption.
>
>> I'm not sure what the desired behavior is.  (i) To silently drop the
>> caption, (ii) to wrap the equation in some sort of float and give it a
>> caption; or (iii) to print the text sans the \caption{·}.
>
>> (iii) can be archived with math-prefix.  (ii) is a bit weird, but
>> could be archived relatively easy, but it's not really what one would
>> expect; it's consistent with how captions work for tables (turned into
>> a float when a caption is present).  (i) is also a bit weird, but
>> seems the most reasonable to me.
>
>> Since I don't know what the correct behavior is, I don't have a patch
>> right now.
>
> IMHO, this is wrong approach. 

I don't understand.

> I would consider this example as a special way to generate a matrix
> when exporting to LaTeX, then CAPTION is useless here. Also, HTML
> export will give differently looking result.

But it shouldn't.  It should produce a matrix as well, e.g. via
MathJax.

–Rasmus


-- 
Summon the Mothership!

Re: [bug][ox-latex] Captions in equations

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> OK.  I can prepare a patch.

Great. Thank you.

> In LaTeX the floating would be kind of odd, I think.  At the very
> least math floats shouldn't be Figure or Tables (IMO); unfortunately
> the Internets seem to suggest that you usually create additional
> floats via packages such as newfloat of "caption".  HTML should also
> be considered...

IIRC there is a "caption" package that can add captions to objects
without making them floats. We could support it, but without requiring
that package by default.


Regards,

-- 
Nicolas Goaziou

Re: [bug][ox-latex] Captions in equations

[Vladimir Lomov]

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

Hello,
** Rasmus [2014-01-19 15:19:40 +0100]:

> Vladimir Lomov <lomov.vl@gmail.com> writes:

>> Hello,
>> ** Rasmus [2014-01-18 20:36:35 +0100]:

>>> Hi,

>>> This example produces invalid LaTeX code:

>>> #+CAPTION: test
>>> #+ATTR_LATEX: :mode math :environment pmatrix
>>> | \alpha | \beta | \gamma |

>>> Namely,

>>> \begin{equation}
>>> \caption{test text}
>>> \mathbf{H}=\begin{pmatrix}
>>>  \vdots & 0 & \vdots \\
>>>  \vdots & H & \vdots \\
>>>  \vdots & 0 & \vdots \\
>>> \end{pmatrix}.
>>> \end{equation}

[...]

>> IMHO, this is wrong approach. 

> I don't understand.

As I said, this is IMHO.

>> I would consider this example as a special way to generate a matrix
>> when exporting to LaTeX, then CAPTION is useless here. Also, HTML
>> export will give differently looking result.

> But it shouldn't.  It should produce a matrix as well, e.g. via
> MathJax.

At first, I wanted to write the following:
  
  And would will be if one doesn't use MathJax? For example, I prefer to
  use dvipng to generate PNG images (there are several reasons for
  this).  So, basically, this is a special case, and an user evidently
  knows about this.

But then I tried to export this example document to HTML with MathJax
and it fails. Consider these two examples: 'ex-tbl.org' and
'ex-tbl2.org' (attached to the message). After exporting first to html I
get 'ex-tbl.html' without MathJax, the second has MathJax but only for
formula. As I expected, problem occurs only for LaTeX export, due to a
bit weird combination.

I'm not a mathematician but I read many books on mathematics and
theoretical physics (I'm a physicist) and don't remember examples of use
an equation with a caption. Equation enclosed into a frame, yes, I see
and use that, numbered or tagged equations, even placed into a float
(though didn't try yet).

Again, this was my IMHO. And I can't imagine situation when I would need
a caption for equation, because there are other ways to emphasize an
equation. What I see from this special example is how it is convenient
to create a matrix for "math mode" in Org document.

> –Rasmus

---
WBR, Vladimir Lomov

-- 
  Monotheism is a gift from the gods.

[-- Attachment #2: ex-tbl.org --]
[-- Type: application/vnd.lotus-organizer, Size: 149 bytes --]

[-- Attachment #3: ex-tbl2.org --]
[-- Type: application/vnd.lotus-organizer, Size: 229 bytes --]

[-- Attachment #4: ex-tbl.html --]
[-- Type: text/html, Size: 5550 bytes --]

[-- Attachment #5: ex-tbl2.html --]
[-- Type: text/html, Size: 7150 bytes --]

Re: [bug][ox-latex] Captions in equations

[Rasmus]

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Hello,
>
> Rasmus <rasmus@gmx.us> writes:
>
>> OK.  I can prepare a patch.
>
> Great. Thank you.
>
>> In LaTeX the floating would be kind of odd, I think.  At the very
>> least math floats shouldn't be Figure or Tables (IMO); unfortunately
>> the Internets seem to suggest that you usually create additional
>> floats via packages such as newfloat of "caption".  HTML should also
>> be considered...
>
> IIRC there is a "caption" package that can add captions to objects
> without making them floats. We could support it, but without requiring
> that package by default.

Sure, nofloat is part of the caption package.  Likewise subcaption.
It's one of the best LaTeX bundles around.

–Rasmus

-- 
Send from my Emacs

Re: [bug][ox-latex] Captions in equations

[Rasmus]

Hi Vladimir,


Vladimir Lomov <lomov.vl@gmail.com> writes:

>>> IMHO, this is wrong approach. 
>> I don't understand.
> As I said, this is IMHO.

I just didn't understand that sentence.  I was not disputing your
opinion.

>>> I would consider this example as a special way to generate a matrix
>>> when exporting to LaTeX, then CAPTION is useless here. Also, HTML
>>> export will give differently looking result.
>
>> But it shouldn't.  It should produce a matrix as well, e.g. via
>> MathJax.
>
> At first, I wanted to write the following:
>   
>   And would will be if one doesn't use MathJax? For example, I prefer to
>   use dvipng to generate PNG images (there are several reasons for
>   this).  So, basically, this is a special case, and an user evidently
>   knows about this.

Hence the "e.g.".

> But then I tried to export this example document to HTML with MathJax
> and it fails. Consider these two examples: 'ex-tbl.org' and
> 'ex-tbl2.org' (attached to the message). After exporting first to html I
> get 'ex-tbl.html' without MathJax, the second has MathJax but only for
> formula. As I expected, problem occurs only for LaTeX export, due to a
> bit weird combination.

Sure.  HTML currently does not understand "matrix-tables".  I'm pretty
sure you know the following already: but what Org does, when making
math-pngs for HTML, is to generate tex files that are processed with
dvipng (as far as I remember).  Since a while ago amsmath is a default
package in Org so a ox-html solution would also be able to work with
png files.  The patch that I posted somewhere else isn't tested with
pngs yet, but it will be.

> I'm not a mathematician but I read many books on mathematics and
> theoretical physics (I'm a physicist) and don't remember examples of use
> an equation with a caption. Equation enclosed into a frame, yes, I see
> and use that, numbered or tagged equations, even placed into a float
> (though didn't try yet).

I have seen framed boxes some times, and even floats, but never
caption.  I never attested to the usefulness of equation-captions.
Though, I'm sure you would agree that Org should produce valid TeX
files.

> Again, this was my IMHO. And I can't imagine situation when I would need
> a caption for equation, because there are other ways to emphasize an
> equation. What I see from this special example is how it is convenient
> to create a matrix for "math mode" in Org document.

It is indeed a great way to type matrices.  Nicholas implemented is a
while ago.

–Rasmus

-- 
⠠⠵

Re: [bug][ox-latex] Captions in equations

[Rasmus]

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

Nicolas,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

>> OK.  I can prepare a patch.
>
> Great. Thank you.
>
>> In LaTeX the floating would be kind of odd, I think.  At the very
>> least math floats shouldn't be Figure or Tables (IMO); unfortunately
>> the Internets seem to suggest that you usually create additional
>> floats via packages such as newfloat of "caption".  HTML should also
>> be considered...
>
> IIRC there is a "caption" package that can add captions to objects
> without making them floats. We could support it, but without requiring
> that package by default.

Attached is a simple patch that works by silently drops the caption in
a sneaky way.  I didn't experience any problems when testing it, but
you might have more insights as to whether this approach have latent
issues.

I think we had the discussion with leaving out packages earlier, when
discussing things like wrap-float etc.  As I recall, the consensus was
to include the necessary packages.  Thus, I think solution (iii) would
require adding caption to the default package alist.  Caption is a
package that's very good, so I wouldn't mind it.  But, I'm still not
convinced that non-floating caption for equation is the correct
behavior.

–Rasmus

-- 
ツ

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Drop-caption-in-ox-latex-math-tables.patch --]
[-- Type: text/x-diff, Size: 1445 bytes --]

From 3470c44a7ef48a92848c39741b25e7c7cf0dddf8 Mon Sep 17 00:00:00 2001
From: Rasmus <w530@pank.eu>
Date: Sat, 25 Jan 2014 15:27:30 +0100
Subject: [PATCH] Drop caption in ox-latex math-tables

* ox-latex.el (org-latex--math-table): Drop captions silently.
---
 lisp/ox-latex.el | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 4522c6b..4f961cb 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -2577,7 +2577,10 @@ used as a communication channel.
 
 This function assumes TABLE has `org' as its `:type' property and
 `inline-math' or `math' as its `:mode' attribute.."
-  (let* ((caption (org-latex--caption/label-string table info))
+  (let* (;; Silently drop captions as they are not supported in
+	 ;; math-mode.
+	 (caption (org-latex--caption/label-string
+		   (org-element-put-property table :caption nil) info))
 	 (attr (org-export-read-attribute :attr_latex table))
 	 (inlinep (equal (plist-get attr :mode) "inline-math"))
 	 (env (or (plist-get attr :environment)
@@ -2651,8 +2654,7 @@ This function assumes TABLE has `org' as its `:type' property and
 				'(0 nil))
 			  (funcall same-mode-p prev))
 		(setq cluster-beg prev))
-	      (and (or (org-element-property :caption cluster-beg)
-		       (org-element-property :name cluster-beg))
+	      (and (org-element-property :name cluster-beg)
 		   "\n\\end{equation}")))
 	   (t "\\]")))))
 
-- 
1.8.5.3

Re: [bug][ox-latex] Captions in equations

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> Attached is a simple patch that works by silently drops the caption in
> a sneaky way.  I didn't experience any problems when testing it, but
> you might have more insights as to whether this approach have latent
> issues.

Thank you.

Altering the parse tree seems a bit drastic to me, though. See below.

> I think we had the discussion with leaving out packages earlier, when
> discussing things like wrap-float etc.  As I recall, the consensus was
> to include the necessary packages.  Thus, I think solution (iii) would
> require adding caption to the default package alist.  Caption is a
> package that's very good, so I wouldn't mind it.  But, I'm still not
> convinced that non-floating caption for equation is the correct
> behavior.

We don't need to add "caption" to the default packages set. We can
specify that this feature is available only if that package is required.

> -  (let* ((caption (org-latex--caption/label-string table info))
> +  (let* (;; Silently drop captions as they are not supported in
> +	 ;; math-mode.
> +	 (caption (org-latex--caption/label-string
> +		   (org-element-put-property table :caption nil) info))

We could replace

  (caption (org-latex--caption/label-string ...))

with

  (label (let ((label (org-element-property :name table)))
           (and label (format "\\label{%s}\n" (org-export-solidify-link-text label)))))

and change "caption" into "label" later in the function.

WDYT?


Regards,

-- 
Nicolas Goaziou