3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-18 22:25:44 +01:00

Keep an image's title as its caption, since a title counts as content; file the two title drops it exposes

This commit is contained in:
2026-10-18 12:56:51 +02:00
committed by Lillem4n
parent 6e7e872c79
commit 2db86f6666
4 changed files with 38 additions and 40 deletions
+1
View File
@@ -28,6 +28,7 @@ In `docs/decisions.md`:
- Tables
- Links
- An image reads as an image only alone in its paragraph, else as its alt text linked; a link text of hard breaks alone reads as its destination, then the breaks
- An image's title is its caption when the image stands alone in its paragraph, since a title counts as content
- A mark skips a node that cannot hold it, and a directive mark wrapping only such nodes is refused, as is a `[text](url)` link unless its text is hard breaks alone
- A linked image is written `[![alt](url)](href)`, a captioned image as its directive
- A linked image standing inline in portable markdown, its link to another target, is written `[alt](href) ([image](url))`
+3 -3
View File
@@ -177,7 +177,7 @@ whatever it costs; the Achieve goals are weighed against each other in the order
- Counter-signal: `spec/flavour.md` gains a special case for each such pick.
- Why: output fitted case by case is output no reader can predict.
1. **Maintain:** A function's name says which markdown it reads or writes.
7. **Maintain:** Lossy conversion drops form, never content.
7. **Maintain:** Lossy conversion drops form, never content. A title counts as content.
8. **Maintain:** Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect.
9. **Maintain:** Fast, and linear in the document's size as JSON.
10. **Achieve:** Easy for a contributor to understand and change safely.
@@ -373,8 +373,8 @@ Ping !adf:mention[@Mikael]{id=5b10a2} — !adf:status[In review]{color=yellow}
Serves [Goals](#goals) 7. Portable markdown is a second flavour of the same grammar.
`adfToPortableMarkdown` writes markdown other tools render — GitHub, GitLab, Obsidian and the like —
keeping the content and dropping the rest: attributes, colours, layout, identity. Content is what a
reader of the rendered document sees or follows: its text, images and link targets. It writes no
directive.
reader of the rendered document sees or follows, titles included: its text, images and link targets.
It writes no directive.
`portableMarkdownToAdf` reads CommonMark and `~~` as `losslessMarkdownToAdf` reads them, and the
conventions below as nodes, taking other tools' spellings too. It reads GFM's pipe tables with or
+14 -8
View File
@@ -243,7 +243,8 @@ reads as its destination, then those breaks: four of seven readers expected that
`[]()` reads as nothing: it renders nothing, so Goal 7 loses no content. A link alone in its
paragraph whose whole text is one image reads as that image, with the link marking its `media`.
Inside any other link, the alt text is plain text the link marks, and the image's URL and title
drop: the panel chose this by Goal 6, which outranks Goal 7.
drop. The panel chose this by Goal 6, but Goal 7 holds the image and its title as content, so this
stands only until `todo.md` item 122 ends it.
In `portableMarkdownToAdf`, a `[!WORD]` marker with no `+` or `-` stands apart from the lines after
it, and so does a `+` or `-` callout's title line, so an image alone on the marker line or after the
@@ -256,10 +257,16 @@ The same panel confirmed the other readings on 2026-10-09: a title as the captio
text as linked alt text, and an empty link text as its URL, each 3 of 3; `[]()` as nothing, 5 of 7.
Their CommonMark suite exceptions are `node-model` (§The CommonMark suite checks three ways).
A reader panel on 2026-10-18 read the title again: seven readers across the bot, the LLM pipeline,
a support agent and a product manager. Two picked a caption, two the picture alone, and three neither,
each describing hover text, which ADF holds no node for. No output reached the five of seven that settles a panel, so the
title still reads as the image's caption until `todo.md` item 121 is answered.
The title's caption, and the reader panel of 2026-10-18 that tested it, are in §An image's title is its
caption when the image stands alone in its paragraph.
## An image's title is its caption when the image stands alone in its paragraph, since a title counts as content
2026-10-18, the maintainer, after a reader panel of seven split: two picked the caption, two the
picture alone, and three neither, and those three described hover text. No output reached the five
of seven that settles a panel, so the goal decided. Goal 7 counts a title as content, so the title keeps its words,
and ADF holds no hover text for an image, so the caption is the one ADF node that keeps them. Valid
while a title counts as content (`README.md` `## Goals`, Goal 7).
## A mark skips a node that cannot hold it, and a directive mark wrapping only such nodes is refused, as is a `[text](url)` link unless its text is hard breaks alone
@@ -286,9 +293,8 @@ Goal 6. Valid while the audience reads a title as hover text.
`adfToLosslessMarkdown` writes a `media` whose only mark is a link as `[![alt](url)](href)`, which
each reader expected before seeing the options. A captioned image keeps the `!adf:caption`
directive: each reader read `![alt](url "title")` as hover text, not a caption. The library's readers
still build a title as the image's caption; a reader panel on 2026-10-18 did not settle whether they
should (§An image reads as an image only alone in its paragraph), and `todo.md` item 121 asks the
maintainer for the answer.
build a title as the image's caption, since a title counts as content (§An image's title is its
caption when the image stands alone in its paragraph).
## A linked image standing inline in portable markdown, its link to another target, is written `[alt](href) ([image](url))`
+20 -29
View File
@@ -6,13 +6,12 @@
`Bar = 0.1`
`Next ID = 122`
`Next ID = 124`
## Items
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 121 | 0.3.0 | | question | **Decide whether an image's title stays its caption, in a goal in `README.md` or a decision in `docs/decisions.md`.** | 1 | 2 | 2 | 3 | 2 | | 0.0 |
| 115 | 0.3.0 | | defect | **Build text holding no `border` mark in `losslessMarkdownToAdf`, and have `adfToLosslessMarkdown` carry text holding one.** | 2 | 1 | 2 | 3 | 3 | 4 by 3 | 4.8 |
| 60 | 0.3.0 | | decision | **Collect the questions `parse/` asks `emit/` into one named module.** | 2 | 1 | 2 | 3 | 4 | 10 by 4 | 4.0 |
| 92 | 0.3.0 | | | **Lower the reading cost of the files a chunk reads most before its first commit.** | 2 | 1 | 1 | 2 | 4 | 10 by 4 | 4.0 |
@@ -23,7 +22,9 @@
| 62 | 0.3.0 | | decision | **Move the portable flavour's reading out of `parse/` and its writing out of `emit/` into `markdown/portable/`, so `emit/` no longer imports `portable/`.** | 3 | 1 | 2 | 4 | 5 | 10 by 5 | 3.0 |
| 33 | 0.3.0 | | defect | **Emit a line in time linear in its mark runs, in `adfToLosslessMarkdown` and `adfToPortableMarkdown`.** | 3 | 1 | 2 | 4 | 5 | 9 by 3 | 2.0 |
| 109 | 0.3.0 | | defect | **Spell nested lists and quotes in time linear in the markdown.** | 3 | 1 | 2 | 4 | 5 | 9 by 3 | 2.0 |
| 73 | 0.3.0 | 33, 59, 60, 62, 91, 92, 95, 102, 109, 115, 121 | | **Announce the package where someone needing an ADF converter already reads: JRACLOUD-77436, the Atlassian developer community and Stack Overflow's ADF-to-markdown questions.** | 1 | 2 | 2 | 3 | 2 | 3 by 8 | 17.4 |
| 73 | 0.3.0 | 33, 59, 60, 62, 91, 92, 95, 102, 109, 115 | | **Announce the package where someone needing an ADF converter already reads: JRACLOUD-77436, the Atlassian developer community and Stack Overflow's ADF-to-markdown questions.** | 1 | 2 | 2 | 3 | 2 | 3 by 8 | 17.4 |
| 123 | 0.3.0 | | defect | **Spell a link title that holds a pipe inside a portable table cell, instead of dropping the title.** | 2 | 1 | 2 | 3 | 2 | 7 by 2 | 4.4 |
| 122 | 0.3.0 | | defect | **Keep an image's URL and title when a link marks the image's alt text, as Goal 7 requires.** | 3 | 1 | 2 | 4 | 5 | 7 by 4 | 2.6 |
| 112 | 0.4.0 | | | **Pad a GFM pipe table's short rows with empty cells, read its body rows holding no pipe, and read a one-column table without leading pipes in `portableMarkdownToAdf`.** | 2 | 1 | 2 | 3 | 3 | 4 by 4 | 6.3 |
| 80 | 0.4.0 | | | **Name the node's path and the attribute key when `not-an-adf-document` refuses a node inside the document.** | 2 | 1 | 2 | 3 | 3 | 6 by 4 | 6.2 |
| 81 | 0.4.0 | | | **Fail the gate unless the README's error tables list exactly the codes `ConvertErrorCode` holds.** | 1 | 1 | 1 | 1 | 2 | 3 by 2 | 4.4 |
@@ -57,32 +58,6 @@
## Details
### 121. Decide whether an image's title stays its caption, in a goal in `README.md` or a decision in `docs/decisions.md`.
Seven readers read `![Moon over the hills](https://docs.example.com/images/moon-over-hills.jpg "The
moon, at night")` alone in its paragraph: the bot, the LLM pipeline, a support agent and a product
manager, some of them twice. Each wrote what it expected to see in Jira or Confluence, then picked
the picture with the title printed under it, the picture alone, or neither. Two picked the caption,
two the picture alone, and three neither, expecting the title as hover text. No output reached five
of seven.
ADF holds no node for hover text, so the caption is the only ADF place for the title's words. Goal 7
says lossy conversion drops form, never content. The README's portable section defines content as
what a reader sees or follows. A hover title is seen only when the pointer rests on the picture.
The goals do not say whether a
title is content. Earlier entries on what an image's title reads as: §An image reads as an image only alone in its paragraph (the
caption, 2026-10-09, 3 of 3); §A linked image is written `[![alt](url)](href)`, a captioned image as
its directive (2026-10-11, 3 of 3, reading a title as hover text); and, inside another link, a title drops,
chosen by Goal 6 over Goal 7 (§An image reads as an image only alone in its paragraph).
Candidate entry: an image's title becomes its caption when the image stands alone in its paragraph,
because ADF holds no hover text and the caption keeps the title's words. This image keeps "The moon, at night"
as visible text under the picture. The other answer drops the title, so the picture stands alone;
Goal 7 allows that only if a title is not content.
Blocks 73: the announcement waits for this answer, since the answer may change what the package
writes for a titled image.
### 115. Build text holding no `border` mark in `losslessMarkdownToAdf`, and have `adfToLosslessMarkdown` carry text holding one.
`!adf:border[x]{color="#091e42" size=2}` builds text holding `border`, which
@@ -175,6 +150,22 @@ posting, set `converter-comparison/run.sh`'s pins to each package's latest versi
its versions and its date in step with the output. We draft each post for the place it goes; the
maintainer posts them once `0.3.0` is published. Found while planning discoverability, 2026-10-04.
### 123. Spell a link title that holds a pipe inside a portable table cell, instead of dropping the title.
In a table cell, `adfToPortableMarkdown` writes a link whose title holds a `|` without the title
(`portableLink` in `src/markdown/portable/inline-reduction.ts`). The same fallback drops a title
that no CommonMark title spelling holds. README `## Goals` Goal 7 counts a title as content, so the
drop breaks a Maintain goal today. GFM reads `\|` inside a table cell as a pipe, so the title can
keep its pipe as `\|`. The reader must read it back to the same title.
### 122. Keep an image's URL and title when a link marks the image's alt text, as Goal 7 requires.
Inside any other link, the reader turns an image into its alt text, linked, and drops the image's
URL and title (`docs/decisions.md` §An image reads as an image only alone in its paragraph). README
`## Goals` Goal 7 holds an image and a title as content, and a Maintain goal holds whatever it
costs. ADF holds no inline external image, so the item must find a shape that keeps the image, its
title and the link together.
### 112. Pad a GFM pipe table's short rows with empty cells, read its body rows holding no pipe, and read a one-column table without leading pipes in `portableMarkdownToAdf`.
GFM pads a short row with empty cells, reads a line holding no `|` after a table as a row, and