mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-21 15:42:58 +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:
@@ -28,6 +28,7 @@ In `docs/decisions.md`:
|
|||||||
- Tables
|
- Tables
|
||||||
- Links
|
- 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 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 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 `[](href)`, a captioned image as its directive
|
- A linked image is written `[](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))`
|
- A linked image standing inline in portable markdown, its link to another target, is written `[alt](href) ([image](url))`
|
||||||
|
|||||||
@@ -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.
|
- 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.
|
- 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.
|
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.
|
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.
|
9. **Maintain:** Fast, and linear in the document's size as JSON.
|
||||||
10. **Achieve:** Easy for a contributor to understand and change safely.
|
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.
|
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 —
|
`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
|
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
|
reader of the rendered document sees or follows, titles included: its text, images and link targets.
|
||||||
directive.
|
It writes no directive.
|
||||||
|
|
||||||
`portableMarkdownToAdf` reads CommonMark and `~~` as `losslessMarkdownToAdf` reads them, and the
|
`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
|
conventions below as nodes, taking other tools' spellings too. It reads GFM's pipe tables with or
|
||||||
|
|||||||
+14
-8
@@ -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
|
`[]()` 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`.
|
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
|
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
|
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
|
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.
|
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).
|
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,
|
The title's caption, and the reader panel of 2026-10-18 that tested it, are in §An image's title is its
|
||||||
a support agent and a product manager. Two picked a caption, two the picture alone, and three neither,
|
caption when the image stands alone in its paragraph.
|
||||||
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.
|
## 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
|
## 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 `[](href)`, which
|
`adfToLosslessMarkdown` writes a `media` whose only mark is a link as `[](href)`, which
|
||||||
each reader expected before seeing the options. A captioned image keeps the `!adf:caption`
|
each reader expected before seeing the options. A captioned image keeps the `!adf:caption`
|
||||||
directive: each reader read `` as hover text, not a caption. The library's readers
|
directive: each reader read `` 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
|
build a title as the image's caption, since a title counts as content (§An image's title is its
|
||||||
should (§An image reads as an image only alone in its paragraph), and `todo.md` item 121 asks the
|
caption when the image stands alone in its paragraph).
|
||||||
maintainer for the answer.
|
|
||||||
|
|
||||||
## A linked image standing inline in portable markdown, its link to another target, is written `[alt](href) ([image](url))`
|
## A linked image standing inline in portable markdown, its link to another target, is written `[alt](href) ([image](url))`
|
||||||
|
|
||||||
|
|||||||
@@ -6,13 +6,12 @@
|
|||||||
|
|
||||||
`Bar = 0.1`
|
`Bar = 0.1`
|
||||||
|
|
||||||
`Next ID = 122`
|
`Next ID = 124`
|
||||||
|
|
||||||
## Items
|
## Items
|
||||||
|
|
||||||
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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 |
|
| 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
|
## 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 `` 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 `[](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.
|
### 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
|
`!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
|
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.
|
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`.
|
### 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
|
GFM pads a short row with empty cells, reads a line holding no `|` after a table as a row, and
|
||||||
|
|||||||
Reference in New Issue
Block a user