jgm
Enhanced Doc for altering pandoc Figures using Lua filter/writer
First of all, I'm aware that this issue might not be of much relevance for experienced users and, as well, might be due to my limited Lua knowledge. Unfortunately, the mailing list ist still down and stackoverflow doesn't present any answer. Thus, I'm writing here.
Since a few days I'm trying to write a Lua filter/partly writer to rearrange and add to the output of the Latex macros for figures including images and captions converting from md to latex. I've read the Lua filter docs as well as some general Lua introductions but can't get it to work.
I got (simplified for testing purposes):
Figure = function(elem)
local raw_elem = '\\begin{figure*}\n' .. elem.content .. '\n' .. elem.caption.long .. '\n\\end{figure*}'
return pandoc.RawBlock('latex', raw_elem)
end
But get bad argument #2 to 'concat' (table expected, got string) as error.
In contrast, following (inspired by the writer example works:
CodeBlock = function(elem)
local raw_elem = '\\begin{code}\n' .. elem.text .. '\n\\end{code}'
return pandoc.RawBlock('latex', raw_elem)
end
The reason seems to be the Blocks character of Figure.content and caption.long in the first example in contrast to the string of CodeBlock.text
I tried many different aspects, but couldn't get it to work.
Unfortunately, the docs don't seem to contain further information's and examples how to alter the complex figures introduced with pandoc 3.0.
Even if I have some experience writing code, a more detailed doc would've helped me a lot.
As initially mentioned, I fully understand if this suggestion paired with a question is not fitting here in the issues area and, thus, might be closed. Then I'll wait for stack overflow or a (re)opened mailing list.
Have a nice day, everyone.
The reason seems to be the Blocks character of Figure.content and caption.long in the first example in contrast to the string of CodeBlock.text
That's right.
local raw_elem = '\\begin{figure*}\n' .. elem.content .. '\n' .. elem.caption.long .. '\n\\end{figure*}'
This is trying to concatenate a string with elem.content, which is a Blocks.
What you should do is create separate RawBlocks for the "begin" and "end" commands, and concatenate these with the Blocks parts. Remember, your filter can return Lua array (table), which will be spliced in, and this can contain both RawBlocks and other stuff.
Thanks for the explanation. That makes totally sense. I'll try it asap.
I just checked the Lua filter docs webpage and searched for "concat". Such an explanation is missing from the page. Since examples like the one with the CodeBlock from the custom writer page can suggest, at least for people like me with limited Lua knowledge, that the pandoc.RawBlock could also work with Block contents, it might be helpful for some users if a short paragraph would be added regarding the possibilities how to edit the output of Figures and other element with such block contents (BlockQuote e.g.); maybe with a similar code example like for the CodeBlock element.
At least in my case that would've been very helpful. But, of course, just a personal preference.
The Lua filter docs are definitely written from the perspective of someone who is quite conversant in the Pandoc API and Lua. I also struggled trying to do something relatively simple with figures, failed, and ultimately just fell back to using IMAGE. I wonder if the Lua examples which are more practical, could be split out and expanded, and people could contribute examples to add to them. Of course as this is open-source, we just need someone who is good at Lua and knows enough to make a useful contribution. I think the debugging section would be critical, as a new user who is not Lua literate can go a long way with the logging.lua file and/or mobdebug to understand how the document is structured...
There are a bunch of practical examples at https://github.com/pandoc/lua-filters
I definitely agree that the docs could be made more user-friendly. It's just a matter of developer time. Maybe someone who is expert in pandoc Lua filters will want to take on this project.
There are a bunch of practical examples at https://github.com/pandoc/lua-filters
These filters are great. I, for instance, use the short caption filter by @tarleb in almost every workflow. But there is no example which handles the "complex figure" elements introduced with pandoc 3.0. Most of the filters are older than a year, and, thus, are written before 3.0. Plus new ones wont be added since the repo is retired.
I also searched stackoverflow for posts since January 2023 (release of pandoc 3.0) with many combinations of the keywords lua, pandoc, figure(s), writer, output and some others. There were some great solutions for kind of similar problems which made me understand the whole backend a bit better. But no concrete example for rearranging the newly introduced pandoc.Figures. (Of course, the possibility exists that I might have missed a post/answer etc.)
That is all not meant as some kind of criticism. It only shows that there aren't many informations on this part of editing pandoc's processing workflow. Thus, it might be very welcome if somebody feels called to enhance the Lua filter docs. But I understand that it is not too less work a voluntary Lua expert, plus the time since January 2023 was rather short. If I ever become an expert in Lua myself, I'll let you know ;-) . At least, I'll share my solution for the specific problem, as soon as I find one.
At least I got a working Lua filter solution for a starred environment, posted in another issue discussion
After reading some other issues with similar topics, I think it would be great to add a more general description to the docs, how to use the new pandoc.Figure elements. E.g. how to wrap a code block (similar to the #+attr_latex :float t option in Emacs org-mode) or any other block like element inside a floating figure.
Considering this, a general caption syntax like mentioned in #9261 would be great too.
I know that's not to less work, but just as an idea for the foreseeable future.