Listing caption formatting inconsistent with figures and tables.

[leenamurgai]

I am converting from LaTeX to HTML5 and trying to use pandoc-crossref version 2.14.02 for cross references to figures, tables, listings and equations. I noticed that in the resulting HTML, the caption is formatted as a paragraph:

<div id="lst:label" class="listing">
<p>caption_text</p>
<pre label="lst:label"><code>code</code></pre></div>

Is there some way to make the formatting more consistent with that of figures and tables?

I think the accepted way to include captions for code in HTML is to wrap it in a table or figure environment and use the caption associated with that. I believe the convention is to caption code listings above it rather than below the listing. At least this is the default in the LaTeX lstlisting package.

If you go with table you need the width to be set to 100% so that the caption takes up the text width. I don't know if you can do that with the AST. In HTML we'd want something like:

<div id="lst:label" class="listing">
<table width=100%>
<caption>
caption_text.
</caption>
</table>
<pre label="lst:label"><code>code</code></pre></div>

If you use figure instead, I think the caption will be forced to be below the code listing (rather than above) but an advantage is that often the default is for the caption to take up the text width so setting the width is not an issue. In HTML we'd want something like:

<div id="lst:label" class="listing">
<figure>
<figcaption>
caption_text.
</figcaption>
<pre label="lst:label"><code>code</code></pre>
</figure></div>

I don't know what the best choice is or if this is an improvement that would be easy to implement but these are some considerations I thought of. Hopefully this makes sense.

[lierdakil]

Right. The issue is, there's no designated figure element in pandoc AST¹, and most output formats don't have anything like that either, html5 being more of an exception. I really, really don't want to add more ad-hoc hacks for specific output formats, it gums up the code base pretty quick.

If you think an abstract figure element in pandoc AST may be useful for code blocks etc, feel free to chime in here: jgm/pandoc#3177.

Using tables isn't great because it'll break in most "interesting" output formats, like docx and pdflatex, and semantically is arguably worse than using a div.

In HTML, divs pretty much give you the same flexibility as figure elements visually if you don't mind adding a little CSS, so I find it's a reasonable middle ground.

---

¹ just in case, AST means "abstract syntax tree", i.e. the internal representation pandoc uses for documents.

[leenamurgai]

If you think an abstract figure element in pandoc AST may be useful for code blocks etc, feel free to chime in here: jgm/pandoc#3177.

Done.

In HTML, divs pretty much give you the same flexibility as figure elements visually if you don't mind adding a little CSS, so I find it's a reasonable middle ground.

Good to know, thanks.