Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/case-study/parsing-ast.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Document
├── Heading { level, content, id? }
├── Paragraph { content }
├── CodeBlock { language?, content, attributes }
├── BlockQuote { blocks, attribution? }
├── BlockQuote { blocks }
├── List { type, tight, items }
│ └── ListItem { blocks, checked? }
├── Table { headers, rows, alignment[] } // alignment[] = column defaults
Expand Down
2 changes: 1 addition & 1 deletion docs/cheatsheet.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Bare delimiters work only at word boundaries; force one intraword with the brace
: definition

> blockquote
^ Attribution (caption / attribution: ^ prefix)
^ Attribution (caption: ^ prefix; wraps the quote in a figure)

> quoted (+ at col 0 attaches the next flush-left
+ block to the quote - no > prefixing)
Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ features:
- title: Interactive Online, Readable Offline
details: "Built for the interactive web first — diagrams, math, charts and tabs hydrate into rich output online. With no JavaScript every block degrades to clean semantic HTML: a Mermaid fence still shows its source, <details> stays native, tables stay tables."
- title: Captions Everywhere
details: One ^ prefix captions images, tables, listings and equations — emitting semantic figure / figcaption / caption HTML. On a blockquote it is an attribution instead, and renders footer.
details: One ^ prefix captions images, blockquotes, tables, listings and equations — emitting semantic figure / figcaption / caption HTML.
- title: Friendly Tables
details: "|= for headers, ^ for rowspan, < for colspan, + for multi-line cells. No separator row required."
- title: Built-in Extensions
Expand Down
5 changes: 2 additions & 3 deletions docs/native-features-analysis.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,9 +80,8 @@ part of Carve syntax; the examples remain as a feature-level reference.
Output varies by context:
- Images → `<figure>` + `<figcaption>`
- Tables → `<caption>` element
- Blockquotes → `<footer>` inside the `<blockquote>`: the line names the source
of the quotation rather than describing it, so it is an attribution and is not
numbered as a figure
- Blockquotes → `<figure>` + `<figcaption>`, which is where the HTML Standard
puts a quotation's attribution: outside the `<blockquote>`, never inside it

### 2. Abbreviations

Expand Down
51 changes: 0 additions & 51 deletions docs/versioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,57 +142,6 @@ To find affected documents, search for the seven names used as attributes on a
span, and for `:name[…]` with any of them. Where a value mattered, move it to an
attribute that survives - a `title`, or a link if it was a URL.

**A captioned block quote is no longer a figure.** Its caption is the source of
the quotation, which is what it always read as, and the HTML now says so:

```carve
> To be
^ Hamlet
```

```html
<figure> <!-- before -->
<blockquote><p>To be</p></blockquote>
<figcaption>Hamlet</figcaption>
</figure>

<blockquote> <!-- after -->
<p>To be</p>
<footer>Hamlet</footer>
</blockquote>
```

The `^` spelling does not change and no document needs editing. Two things do
change beyond the markup: a quote no longer takes a figure number, so a `#`
placeholder in its caption stays literal and a numbered cross-reference to it
stops resolving; and the AST node is a `block_quote` carrying an `attribution`
rather than a `figure` wrapping the quote, which matters to anything reading the
tree.

There is no replacement for the number in this version. PART 9 §4a describes
writing the figure explicitly, and that form depends on `:::` becoming a
captionable host, which has not landed (carve#1122). Written today it does not
number anything - the caption line is not attached to the fence and renders as
literal text:

```carve
{#ep}
::: figure
> To be
:::
^ Figure #: A pull quote
```

```html
<div class="figure" id="ep">
<blockquote><p>To be</p></blockquote>
</div>
<p>^ Figure #: A pull quote</p>
```

So a quotation that has to carry a figure number needs a host that already takes
one - an image, a table, a listing or an equation - until carve#1122 lands.

### Checking documents mechanically

The marker is machine-readable, so this does not have to be done by eye. In
Expand Down
12 changes: 4 additions & 8 deletions resources/ast-schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -611,13 +611,6 @@
"$ref": "#/$defs/blockNode"
}
},
"attribution": {
"description": "The source of the quotation (PART 9 \u00a74a). Present when a `^` caption attaches to the quote; it is not a figure caption and takes no number.",
"type": "array",
"items": {
"$ref": "#/$defs/inlineNode"
}
},
"attrs": {
"$ref": "#/$defs/attrs"
},
Expand Down Expand Up @@ -1084,11 +1077,14 @@
"const": "figure"
},
"target": {
"description": "The captioned block: an image, table, code block or paragraph. A captioned block quote is NOT a figure - it is a quote carrying an `attribution` (PART 9 \u00a74a, carve#1159).",
"description": "The captioned block: an image, block quote, table, code block or paragraph. What a captioned host is called and counted as comes from the caption's label, never from the host (PART 9 \u00a74b); for a quote the HTML Standard also requires the attribution outside the `blockquote`.",
"oneOf": [
{
"$ref": "#/$defs/image"
},
{
"$ref": "#/$defs/block_quote"
},
{
"$ref": "#/$defs/table"
},
Expand Down
13 changes: 13 additions & 0 deletions resources/engine-pin-drift.txt
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,16 @@
# Emptying this file is the normal end state after `npm run bump-carve-pin`.
#
# Format: <slug><space><space><reason>

# PART 9 §4b (carve#1213): a captioned quote is a FIGURE again. The pinned
# build carries the withdrawn carve#1161 shape and renders
# `<blockquote><footer>`. Clears with the engine reverts and a pin bump.
05-lists-20 A captioned quote renders `<figure><figcaption>`; the pin renders `<blockquote><footer>`.
07-blockquote-with-attribution A captioned quote renders `<figure><figcaption>`; the pin renders `<blockquote><footer>`.
55-blockquote-caption-after-a-blank-line A captioned quote renders `<figure><figcaption>`; the pin renders `<blockquote><footer>`.
282-two-blank-lines-detach-a-caption-5 A captioned quote renders `<figure><figcaption>`; the pin renders `<blockquote><footer>`.
306-a-captioned-quote-holds-more-than-one-block A captioned quote renders `<figure><figcaption>`; the pin renders `<blockquote><footer>`.
306-a-captioned-quote-holds-more-than-one-block-2 A captioned quote renders `<figure><figcaption>`; the pin renders `<blockquote><footer>`.
306-a-captioned-quote-holds-more-than-one-block-3 A captioned quote renders `<figure><figcaption>`; the pin renders `<blockquote><footer>`.
306-a-captioned-quote-holds-more-than-one-block-4 A captioned quote renders `<figure><figcaption>`; the pin renders `<blockquote><footer>`.
306-a-captioned-quote-holds-more-than-one-block-5 A captioned quote renders `<figure><figcaption>`; the pin renders `<blockquote><footer>`.
16 changes: 8 additions & 8 deletions resources/examples/core.md
Original file line number Diff line number Diff line change
Expand Up @@ -961,10 +961,10 @@ Intro

```html
<p>Intro</p>
<blockquote>
<p>Stay hungry</p>
<footer>Steve Jobs</footer>
</blockquote>
<figure>
<blockquote><p>Stay hungry</p></blockquote>
<figcaption>Steve Jobs</figcaption>
</figure>
```

:::
Expand Down Expand Up @@ -1044,10 +1044,10 @@ Only `[x]`/`[X]` render a checked box; every other state (`[ ]`, `[-]`, `[_]`, `
```

```html
<blockquote>
<p>Stay hungry, stay foolish.</p>
<footer>Steve Jobs</footer>
</blockquote>
<figure>
<blockquote><p>Stay hungry, stay foolish.</p></blockquote>
<figcaption>Steve Jobs</figcaption>
</figure>
```

:::
Expand Down
104 changes: 57 additions & 47 deletions resources/examples/edge-cases.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,10 +179,10 @@ quote becomes a `<figure>` with a `<figcaption>`.
```

```html
<blockquote>
<p>quote text</p>
<footer>Source: Someone</footer>
</blockquote>
<figure>
<blockquote><p>quote text</p></blockquote>
<figcaption>Source: Someone</figcaption>
</figure>
```

:::
Expand Down Expand Up @@ -15019,10 +15019,10 @@ one-blank-line form since long before this category existed.
```

```html
<blockquote>
<p>the cited line</p>
<footer>Source: the cited work</footer>
</blockquote>
<figure>
<blockquote><p>the cited line</p></blockquote>
<figcaption>Source: the cited work</figcaption>
</figure>
```

:::::
Expand Down Expand Up @@ -16569,13 +16569,13 @@ The [HTML]{abbr="Custom"} key.

## A captioned quote holds more than one block

PART 9 §4a makes a caption on a block quote its ATTRIBUTION: the source goes
inside the `<blockquote>` as a `<footer>`, and the quote takes no figure number.
A caption makes its host a figure, and PART 9 §4b says a quote is no exception:
the quote goes inside a `<figure>` and the caption becomes its `<figcaption>`,
which is where the HTML Standard puts a quotation's attribution.

The clause does not count the quote's blocks, and nothing else does either. A
multi-paragraph epigraph is ordinary, and so are a quoted list, a nested quote, a
quoted code block and a quoted heading. Each one takes its attribution the same
way, in the same place.
Nothing counts the quote's blocks. A multi-paragraph epigraph is ordinary, and so
are a quoted list, a nested quote, a quoted code block and a quoted heading. Each
one takes its caption the same way, in the same place.

This needed pinning because the executable spec refused every shape but a single
paragraph, and no corpus document held any of the others - so the refusal was
Expand All @@ -16593,17 +16593,19 @@ the gap was guarded by the absence of a fixture rather than by a decision
```

```html
<blockquote>
<p>Nothing in this world is certain except death and taxes.</p>
<p>The second of the two arrives rather more often.</p>
<footer>Benjamin Franklin</footer>
</blockquote>
<figure>
<blockquote>
<p>Nothing in this world is certain except death and taxes.</p>
<p>The second of the two arrives rather more often.</p>
</blockquote>
<figcaption>Benjamin Franklin</figcaption>
</figure>
```

:::

A quoted list. The attribution follows the list inside the quote; it is not a
sibling of it and not an item of it.
A quoted list. The caption belongs to the quote as a whole, so the list stays the
quote's only child and the caption sits outside it.

::: compare

Expand All @@ -16614,20 +16616,22 @@ sibling of it and not an item of it.
```

```html
<blockquote>
<ul>
<li>Be skeptical.</li>
<li>Be kind.</li>
</ul>
<footer>House rules</footer>
</blockquote>
<figure>
<blockquote>
<ul>
<li>Be skeptical.</li>
<li>Be kind.</li>
</ul>
</blockquote>
<figcaption>House rules</figcaption>
</figure>
```

:::

A nested quote. The caption attaches to the OUTER quote - the one whose marker
column the caption line sits against - so the inner quote carries no attribution
of its own.
column the caption line sits against - so the inner quote carries no caption of
its own.

::: compare

Expand All @@ -16637,16 +16641,18 @@ of its own.
```

```html
<blockquote>
<blockquote><p>I never said that.</p></blockquote>
<footer>Quoted in the report</footer>
</blockquote>
<figure>
<blockquote>
<blockquote><p>I never said that.</p></blockquote>
</blockquote>
<figcaption>Quoted in the report</figcaption>
</figure>
```

:::

A quoted code block. The `<pre>` is the quote's only child and the attribution
still lands beside it, which is the case that shows the rule is about the quote
A quoted code block. The `<pre>` is the quote's only child and the caption still
lands beside the quote, which is the case that shows the rule is about the quote
rather than about a paragraph.

::: compare
Expand All @@ -16659,18 +16665,20 @@ rather than about a paragraph.
```

```html
<blockquote>
<pre><code>git bisect run ./check
<figure>
<blockquote>
<pre><code>git bisect run ./check
</code></pre>
<footer>The release runbook</footer>
</blockquote>
</blockquote>
<figcaption>The release runbook</figcaption>
</figure>
```

:::

A quoted heading. The heading keeps its id, and PART 9R leaves it out of the
implicit-reference index because it sits inside a quote - the attribution does
not change that either way.
implicit-reference index because it sits inside a quote - the caption does not
change that either way.

::: compare

Expand All @@ -16682,11 +16690,13 @@ not change that either way.
```

```html
<blockquote>
<h2 id="Terms">Terms</h2>
<p>Delivery is at the discretion of the vendor.</p>
<footer>Appendix B</footer>
</blockquote>
<figure>
<blockquote>
<h2 id="Terms">Terms</h2>
<p>Delivery is at the discretion of the vendor.</p>
</blockquote>
<figcaption>Appendix B</figcaption>
</figure>
```

:::
Expand Down
Loading