[API change] Add a Figure block, modify Table block

[despresc]

Resolves jgm/pandoc#3177 in this library.

The design of Figure is the more expressive one:

data Block
  = ...
  | Figure Attr CaptionPos Caption [Block]
  ...

data CaptionPos = CaptionBefore | CaptionAfter -- should there be a CaptionPosDefault?

and the Caption from Table has been removed, since that seemed to be desired. The idea now is that a few Figure configurations will be special:

• a Figure with [Plain [Image...]] content is a captioned image
• a Figure with a sequence of captioned images as content is a "gallery" of images (could expand this to allow Plain [Image...] blocks in the content, which would be considered captionless sub-images)
• a Figure with [Table...] content is a captioned table
• a Figure with [CodeBlock...] content is a captioned code listing

These map fairly straightforwardly onto a lot of different formats as I mentioned in this comment. Some formats allow for more complex Figure content as well, but all formats will still need to keep these in mind, since they usually have explicit captions in their tables and code listings (when those elements exist). A future numbering/referencing system will need to respect them as well, to make sure that figures and tables can be numbered and referenced properly.

At the start, writers can attempt to render a Figure by instead rendering a Div with an added "figure" class, inside of which is a Div caption and the figure content, the caption being before or after the content depending on what the CaptionPos is. I think that is a decent fallback in future for writers that encounter a Figure in an invalid position or with invalid content for that format, but specific formats might have better ways of handling those situations.

The exceptions are the captioned image and captioned table configurations, which should be detected and handled like implicit figures and tables are now, from the start, to avoid regressions in behaviour.

Each of LaTeX, JATS, DocBook, and HTML support more complex Figure content (which is why the Figure block isn't just a sequence of captioned images). Beyond the special handling of the configurations above, I think the following Figure support is possible in those formats with this design:

• HTML allowing arbitrary block content in figures
• JATS and DocBook allowing figures without figure children (both have some additional restrictions)
• JATS and DocBook 5.2 allowing figures with a sequence of subfigures, corresponding to the <fig-group> and <formalgroup> elements
• LaTeX allowing figures without figure children. While there is the subcaption package for one-deep figure and table nesting, that package needs an explicit figure width in Figure.

There may be other formats that support more complex figures, but I'm not too familiar with them.

[jgm]

Question: does it really make sense to represent the caption position in the figure element itself?

That is desirable if, and only if, we want to give authors the flexibility of having some figure captions above the figures and others below, in the same document. But to me that looks like sloppy layout; I assume most publishers would enforce a consistent style one way or the other.

If that's right, then shouldn't caption position be determined by a document-wide option (a command line option or metadata field)?

I suppose a possible counterargument is this: the spirit of markdown is to have documents readable as they are (quasi WYSIWYG I guess), so setting caption position implicitly by looking at how the author places it makes some sense, even at the cost of allowing sloppy, inconsistent documents.

By the way, the same issues for caption position come up for tables, but currently we don't represent caption position for tables. Presumably we should handle the issue the same way for tables and figures.

[despresc]

I'm not sure. The position of the caption can be chosen on a per-figure basis in the various formats that support them, or at least all the ones that I talked about above. I suppose that's the main reason I added a caption positioning type to Figure and didn't leave it up to a global setting.

I'd have to look around to see if there were house styles that allow for or require captions in different places. I think a somewhat common style is to have table captions above the table and captions for graphical figures below the figure. That could be controlled through metadata easily. Maybe some places advocate that captions be placed differently based on finer figure classes (graphic, code listing, captioned formula) or even based on figure size? But that's just speculation.

[despresc]

If there were a CaptionPosDefault then we could have both, of course. I suppose even without we could have both, now that I think about it.