Extend caption syntax to images and block quotes

doc/syntax.md

@@ -673,14 +673,47 @@ verbatim spans; these do not count as cell separators:
 
     | just two \| `|` | cells in this table |
 
-You can attach a caption to a table using the following syntax:
+Tables support captions; see [Caption] below.
 
-    ^ This is the caption.  It can contain _inline formatting_
-      and can extend over multiple lines, provided they are
-      indented relative to the `^`.
+### Caption
 
-The caption can come directly after the table, or there can
-be an intervening blank line.
+A caption provides a title or description for an element. A caption
+can be attached to a table, an image, or a block quote by placing a
+line starting with `^` followed by a space after the element. The
+caption can come directly after the element, or there can be an
+intervening blank line. The caption text is parsed as inline content
+and can extend over multiple lines, provided they are indented relative
+to the `^`.
+
+For tables, the caption is associated with the table itself:
+
+    | fruit  | price |
+    |--------|------:|
+    | apple  |     4 |
+    ^ Fruit prices in the market
+
+When rendered to HTML, this produces a `<caption>` element inside
+the `<table>`.
+
+When a paragraph contains only an image and is followed by a caption,
+the image becomes a figure - a self-contained unit with its caption:
+
+    ![Sunset over the ocean](sunset.jpg)
+    ^ A beautiful sunset captured at the beach
+
+When rendered to HTML, this uses `<figure>` and `<figcaption>` elements.
+
+A block quote followed by a caption also becomes a figure, which is
+useful for attributions:
+
+    > To be or not to be, that is the question.
+    ^ William Shakespeare, Hamlet
+
+Multi-line captions are supported:
+
+    ![Historic photo](apollo.jpg)
+    ^ This photograph was taken in 1969
+      during the Apollo 11 mission.
 
 ### Reference link definition