Short caption in Markdown figures for \listoffigures

[hadim]

I use \listoffigures in my document. The thing is I use Markdown syntax to insert figures (and I would like to keep this syntax) :

![My too long long catpion for \listoffigures](figures/dolly.png){#fig:dolly}

Note that I also use pandoc-crossref : {#fig:dolly} to avoid using Latex syntax and make Word convertion working nicely with my references !

Anyway, the thing is when I use \listoffigures, the title of the figure in the list are way too long and I would like to only add a short title.

In Latex you can specify a "short caption" like that :

\caption[Short version for LoF]{Long version to appear next to the figure}

Any chance to add this feature in Pandoc ? or any idea for a workaround ?

[hadim]

As a workaround (but only working for Latex), I could add a command to limit the title in \lof to the first sentence of the caption. But I don't know how to do that. I ask the question here : https://tex.stackexchange.com/questions/269613/limit-the-title-in-listoffigures-to-the-first-sentence-of-the-caption

[jgm]

Pandoc doesn't natively support lists of figures anyway -- you can only achieve this with a LaTeX command. So, if you're only targeting LaTeX, you could always use the LaTeX command for the figure too. I think supporting short and long versions of captions in pandoc's Markdown is out of scope.

[waeltken]

Is it really out of scope? What about the images alt text?

![la lune](lalune.jpg "Voyage to the moon")

At the moment the text in the square brackets shows up as caption for figures, could the text in the quotes be uses for the list of figures? So that it would translate to:

\caption[la lune]{Voyage to the moon}

in the latex figure?

[hadim]

That would be really awesome !

[waeltken]

So i don't know pandocs source that well, but it looks like it could be added in the Latex Writer for the figures on line 360. I've not tried building pandoc so maybe I'll take a look at that.

https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Writers/LaTeX.hs#L360

[hadim]

I will try to make this work.

[waeltken]

Actually i've created a commit that should/could work.
But maybe you could try and build it as i am still downloading and building all dependencies.

Feel free to try. If it works I'll send a pull request.

https://github.com/waeltken/pandoc/tree/short_caption_latex_figures

[hadim]

tit does not seem to be the correct variable. I can't find which one I should declare and import.

alt <- inlineToLaTeX (Image alt (src,tit)) does not work...

PS: first time ever I develop in Haskell, so be nice :-)

[waeltken]

I struggle myself, but i think i might have it...
I am not a maintainer though, we will need someone who agrees that this won't break anything and is a useful feature.

Take a look at my branch again. I've ended up with the following lines of changes:

diff --git a/src/Text/Pandoc/Writers/LaTeX.hs b/src/Text/Pandoc/Writers/LaTeX.hs
index 35cd4eb..9b83000 100644
--- a/src/Text/Pandoc/Writers/LaTeX.hs
+++ b/src/Text/Pandoc/Writers/LaTeX.hs
@@ -332,11 +332,12 @@ blockToLaTeX (Para [Image txt (src,'f':'i':'g':':':tit)]) = do
   inNote <- gets stInNote
   capt <- inlineListToLaTeX txt
   img <- inlineToLaTeX (Image txt (src,tit))
+  short <- stringToLaTeX TextString tit
   return $ if inNote
               -- can't have figures in notes
               then "\\begin{center}" $$ img $+$ capt $$ "\\end{center}"
               else "\\begin{figure}[htbp]" $$ "\\centering" $$ img $$
-                      ("\\caption" <> braces capt) $$ "\\end{figure}"
+                      ("\\caption" <> brackets (text short) $$ braces capt) $$ "\\end{figure}"
 -- . . . indicates pause in beamer slides
 blockToLaTeX (Para [Str ".",Space,Str ".",Space,Str "."]) = do
   beamer <- writerBeamer `fmap` gets stOptions

I don't know about this line, if it is actually necessary:

short <- stringToLaTeX TextString tit

And i still can't build pandoc on my machine here. I think ill stop here from now. If you can compile it would be nice to let me know if it works as expected!

[hadim]

Wow ! Nice catch dude !

It works like a charme for me.

# Instruction

You can execute me with `pandoc source.md -o final.tex` and `pandoc source.md -o final.pdf`.

# Figures

![This is a long caption.](http://fakeimg.pl/439x320/282828/ "This a short caption (alt text)")

![This is a long caption 2.](http://fakeimg.pl/439x320/282828/ "This a short caption 2 (alt text)")


\listoffigures

produces

\section{Instruction}\label{instruction}

You can execute me with \texttt{pandoc\ source.md\ -o\ final.tex} and
\texttt{pandoc\ source.md\ -o\ final.pdf}.

\section{Figures}\label{figures}

\begin{figure}[htbp]
\centering
\includegraphics{http://fakeimg.pl/439x320/282828/}
\caption[This a short caption (alt text)]{This is a long caption.}
\end{figure}

\begin{figure}[htbp]
\centering
\includegraphics{http://fakeimg.pl/439x320/282828/}
\caption[This a short caption 2 (alt text)]{This is a long caption 2.}
\end{figure}

\listoffigures

[waeltken]

Could you check if you are using the version 5202c0b of my commit?

 "\\caption" <> brackets (text short) $$ braces capt) $$ "\\end{figure}"

Basically i had two version of which i was unsure. The other was:

 "\\caption" <> brackets (text short) <> braces capt) $$ "\\end{figure}"

Edit:
And also, how did you build install? Simply by using the

cabal install

command?

[hadim]

I manually apply the code with ("\\caption" <> brackets (text short) <> braces capt) $$ "\\end{figure}"

[waeltken]

So it is this version that worked then: 6ff52c3

[hadim]

$$ works also but it produces a newline between [] and {}. I think <> is better.

[waeltken]

Okay great! Now i would like to be able to use it myself... 😭

[hadim]

cabal build && cabal install should work...

Can you open a PR so can discuss there with @jgm ?

[waeltken]

#2447 Sure can do!
I was missing:

git submodule update --init

so now its working for me too!

[ssadedin]

For those interested in an alternative solution to this issue, I implemented an option to automatically create the short caption from the first sentence of the long captions here. It is only implemented for tables and images at the moment, though I don't think it would be difficult to adapt for other captioned elements.

The solution is disabled by default and enabled by a flag, --latex-short-cap, for example:

pandoc --latex-short-cap  -o test.pdf test.md

Unfortunately my changes are based on a slightly older version of Pandoc, and I can see that recent changes have gone in which conflict. Given John's comments above and the conflicting changes, I won't submit a pull request but perhaps this branch will be useful for people in the same position as me (that is, with a whole PhD thesis written using Pandoc and Markdown and for which the unacceptable list of figures & tables is the only real stumbling block!).

I want to thank @hadim and @waeltken who pointed me to the right parts of the code needed to implement this.

[davejm]

This Lua filter allows you to add custom short captions, or automatically tries to use the first sentence of the regular caption as the short caption. https://gist.github.com/davejm/508e7f46b88041497a66c9493b4b4a89

[LunkRat]

@jgm I am commenting here because I am in the same situation as @ssadedin

(that is, with a whole PhD thesis written using Pandoc and Markdown and for which the unacceptable list of figures & tables is the only real stumbling block!).

At the beginning of this issue thread, you stated:

Pandoc doesn't natively support lists of figures anyway -- you can only achieve this with a LaTeX command. So, if you're only targeting LaTeX, you could always use the LaTeX command for the figure too. I think supporting short and long versions of captions in pandoc's Markdown is out of scope.

The suggestion by @waeltken to use Markdown's image title attribute for the LoF title is ideal (and many others agree). This is actually what I intuitively attempted before finding this issue, as I reasoned that the title attribute would be picked up by my pandoc/LaTeX-automated LoF.

Why not feed the Markdown image title text to LaTeX as the LoF title in place of the Markdown alt text attribute? This would allow us to:

![My really long markdown alt text because in scientific papers it's normal to have multi-sentence captions describing a figure and also to have sub-figures labeled as (A) and (B) and so on that you need to describe at length. However, this long alt text is great for my image caption but completely unsuitable for a list-of-figures title and it makes the rendered PDF look like it has some weird bugs and the only explanation you can find is in this GitHub issue.](figures/psychophysics_stimuli.png "My concise figure title for my LoF")

So the issue really isn't that you have to support "short and long versions of captions" you just have to make a change in which the markdown title attribute, if it is supplied, would be used as the LoF title text.

This seems consistent with the standard use of alt text vs title attribute in HTML.

[jgm]

@LunkRat I think it's a decent suggestion, very practical and natural. One drawback, though, is that the title in the AST is just a string, not formatted text. That means you can't have formatting or (e.g.) math. I had assumed that this would be too much of a limitation. Maybe you should open a new issue with the suggestion.

[LunkRat]

Thanks @jgm, done! #7915