Use markdown image title text when generating list of figures

[LunkRat]

Currently if pandoc is called with --lof or configured with a format.yml containing:

---
lof: yes

when converting a markdown source, each figure is listed in the LoF using its markdown alt text. This is a problem as others have pointed out in a separate issue because the alt text is also used for image captions, and the text length desired for image captions is very often longer than a short identifying text needed in a list of figures.

Fortunately markdown offers a title text attribute for images which affords a practical and natural solution. The proposal here is to use the markdown image title when generating the list of figures. Usage would look like this:

[My image **caption** can be long with _formatting_.](figures/my_figure.jpg "Figure title for LoF entry")

The title attribute is simple text only (no formatting or math, etc.) which makes it perfect to use in an LoF entry where you don't want that anyway.

This solution allows for a semantic separation between image caption (markdown alt text) and LoF entry text (markdown title text).

[jgm]

I guess my main question is whether it's too much of a limitation if this is confined to being plain string content? (no formatting or math, unless the math is plain text unicode) If not, then this does seem a nice solution, until we get fancier figure support worked out.

[LunkRat]

My understanding is that a list of figures in a document should contain only plain text strings to identify each figure. In my opinion being restricted to plain text is a virtue in this case.

[jgm]

I can imagine wanting short figure titles like:

• Alliances in the Iliad
• Frequency of copain vs pote
• Graph of $y=x^2$

[LunkRat]

@jgm You make a fair point. Does the need for italics or math in LoF titles outweigh the need for the ability to have figure captions/alt text be independent of LoF titles which this issue is attempting to solve? I argue that formatting LoF titles is a small price to pay in exchange for the ability to write figure captions that are multiple sentences without having them essentially break the LoF by rendering it unrecognizable.

One solution could be to have a conditional that uses the plain text image title attribute if present, otherwise fall back to using the alt text. I don't like this from a usability perspective, but it would allow those folks who want to use formatting in LoF titles to continue to do so using the alt text (would also make this change more backwards compatible).

Thoughts?

[tarleb]

Not a full solution, but for the time being you can use the "short-captions" Lua filter at https://github.com/pandoc/lua-filters/tree/master/short-captions. It only works when going from Markdown to LaTeX and has a few other limitations, but it allows for math in the short caption.

See also #3177, which may have to be completed first.

[LunkRat]

I tried the Lua filter and it works; however, when I combine it with pandoc-fignos from the pandoc-xnos package, the syntax for the Lua short-captions breaks the @fig:[name] in-text figure reference:

[My long alt text figure caption](figures/psychophysics_stimuli.png){#fig:stimuli width=75% short-caption="Psychophysics stimuli"}

The above results in an error from pandoc-fignos when I reference the figure by name with @fig:stimuli:

pandoc-fignos: Bad reference: @fig:stimuli

So while the Lua filter does give the desired behavior, it breaks other desired functionality.

[tarleb]

Make sure that pandoc-xnos runs before the Lua filter. Filters are run in the order in which they appear on the command line.

I wrote an updated, shorter filter that uses new pandoc features and might give better results in some cases:

if FORMAT ~= "latex" then return end

function Para (para)
  if #para.content ~= 1 then return end
  local img = para.content[1]
  if not img or img.t ~= 'Image' or #img.caption == 0
     or img.title:sub(1,4) ~= 'fig:'
     or not img.attributes['short-caption'] then
    return nil
  end

  local short_caption = pandoc.write(
    pandoc.read(img.attributes['short-caption']), FORMAT
  ):gsub('^%s*', ''):gsub('%s*$', '')  -- trim, removing surrounding whitespace

  local figure = pandoc.write(pandoc.Pandoc{para}, FORMAT)
  return pandoc.RawBlock(
    'latex',
    figure:gsub('\n\\caption', '\n\\caption[' .. short_caption .. ']')
  )
end

[LunkRat]

Thank you for the suggestion @tarleb I mistakenly thought I had tried both orders but I tried again and I got your Lua filters to work with pandoc-xnos by ordering my command so that pandoc-xnos filter runs before the Lua filter. I am using the newer, shorter Lua filter you posted on this issue and it works beautifully. So this does indeed solve my immediate need.

I still think it is worth implementing the original issue idea into Pandoc, for two reasons:

1. It would not require any extra filter to be called.
2. It would not require extra syntax above standard markdown. Using the Lua filter approach, documents will get littered with short-caption="[...]" which has no meaning or use outside of the specific Lua filter.

So I'm happy to be all fixed up but I still argue that this issue should be implemented as specified. Thank you @tarleb and @jgm for your attention and help!

[tarleb]

Thanks for the feedback, happy to hear that it works. I think we all agree that this should be implemented and become a part of pandoc. It will be easy once support for figures has been improved, and I hope to do that soon.

[jgm]

The reason I'm hesitant to implement this suggestion now is that the plain string limitation seems like a problem.
(And it wouldn't be right to parse it as markdown in the writer, because we don't know that the source was markdown.)

[LunkRat]

@tarleb is there a comparable technique available for something like short-caption that could work for Table captions? I'm hoping to clean up my LoT but I see the statement about lack of support for table captions in the Limitations section of the short-caption lua filter README. If you know of any workarounds for this problem please let me know.