Extend caption syntax to images and block quotes

[dereuromark]

Summary

• Extends the existing ^ caption syntax (currently tables only) to also support images and block quotes
• Extracts caption rules into a dedicated "Caption" section in the spec for clarity
• Image + caption: wraps in <figure> with <figcaption>
• Block quote + caption: wraps in <figure> with <figcaption>, useful for attributions
• Table caption behavior is unchanged (<caption> element)
• Multi-line caption example included

This is a natural extension of the table caption syntax that already exists in the spec, using the same ^ marker consistently across elements.

Examples:

![Sunset over the ocean](sunset.jpg)
^ A beautiful sunset captured at the beach

> To be or not to be, that is the question.
^ William Shakespeare, Hamlet

Addresses #28 and #31.

A reference implementation already exists in djot-php, closing the gap between upstream spec and downstream implementations.

[Omikhleia]

<figure>, <caption>, <figcaption> etc. = does the specification of a lightweight markup language has to be dependent on HTML-derived concepts?

• It's too technical for non tech-savvy readers (who do not bother what HTML is)
• The lightweight markup language may be used in other context that the Web...

[Omikhleia]

(In other terms, the proposal here is confounding the specification of a markup and the actual way it might be rendered in some context, which is by no mean authoritative.)

[dereuromark]

True. Let me rephrase this more agnostically.

[dereuromark]

Omikhleia raises a fair point about HTML-dependency in the spec. A possible approach: lead with semantic description, then mention HTML as an example output.

For instance, instead of:

A table caption produces a <caption> element inside the table

Consider:

A caption provides a title or description for the preceding element. For tables, the caption is associated with the table itself. When rendered to HTML, this becomes a <caption> element.

This keeps the spec useful for HTML users while being output-agnostic in principle. The semantic meaning ("provides a title/description", "is associated with") comes first; the HTML rendering is presented as one possible output, not the definition.

Same pattern could apply to figures:

An image with a caption becomes a figure - a self-contained unit with its caption. When rendered to HTML, this uses <figure> and <figcaption> elements.

This way non-technical readers understand what it does, and technical readers know how it renders.

[Omikhleia]

This being said, I personally like the proposal. So it has two reference implementations

• As stated here, in djot-php
• Also in my modified version of the djot-lua for SILE (which does more than images and blockquotes, see question below)

A third independent implementation would be nice -- typically, for instance, the djot-hs parser (unless mistaken) used by Pandoc, i.e. with respect to the intermediary AST used in that software.

On that topic, regarding:

![Sunset over the ocean](sunset.jpg)
^ A beautiful sunset captured at the beach

It seems to me that the most logical way would to use a Figure element (as generated e.g. when the implicit_figure extension is enabled in Pandoc-style markdown). I am less sure for the blockquote case, but it's probably applicable too (?)

Extra question: why on images and block quotes only, and not generalized to code blocks and divs?

[dereuromark]

Extra question: why on images and block quotes only, and not generalized to code blocks and divs?

95% use case I would say. You gotto stop somewhere.
Code blocks could maybe still be somewhat relevant, but generic divs as a whole seem out of scope (too generic).