3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-21 15:42:58 +01:00

Answer product-owner round 1: 1 🔴, 7 🟡 (0 misread); spell the attributes Jira's editor writes, specify the lossy writer per node, and close the code, table, mention and URL gaps

This commit is contained in:
2026-11-16 23:29:57 +01:00
committed by Lillem4n
parent 4dd42131e1
commit 355714343d
4 changed files with 110 additions and 61 deletions
+1
View File
@@ -97,6 +97,7 @@ In `docs/decisions.md`:
- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its content - Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its content
- Jira wiki markup's writers are `adfToLosslessJiraWiki` and `adfToLossyJiraWiki`, two calls with no option - Jira wiki markup's writers are `adfToLosslessJiraWiki` and `adfToLossyJiraWiki`, two calls with no option
- Jira wiki markup spellings the help leaves open are a writer panel's picks - Jira wiki markup spellings the help leaves open are a writer panel's picks
- A plain wiki spelling stands for the attributes Jira's editor writes, and any other attribute rides the carry
- `htmlToAdf` reads any HTML, with no option and no second call - `htmlToAdf` reads any HTML, with no option and no second call
## 1. Nothing about any consumer in the library ## 1. Nothing about any consumer in the library
+34 -14
View File
@@ -1469,25 +1469,45 @@ refusal. Lands with `todo.md` items 193 to 196.
Seven fresh-context readers, seated as the bot, the viewer/editor app and the LLM pipeline, were Seven fresh-context readers, seated as the bot, the viewer/editor app and the LLM pipeline, were
told the trap: an app saving through the lossy writer loses form on every save, with nothing told the trap: an app saving through the lossy writer loses form on every save, with nothing
refused. All seven picked `adfToLosslessJiraWiki` and `adfToLossyJiraWiki` as two calls over one refused. All seven picked `adfToLosslessJiraWiki` and `adfToLossyJiraWiki` as two calls over one
call with `{ lossy: true }`, and over `adfToPortableWiki`, which reads as the safe choice. The call with `{ lossy: true }`, and over `adfToPortableWiki`, which sounds like the safe choice to a
reader's name is not settled in this entry: the seats split four to three between reader who hasn't seen the trap.
`jiraWikiMarkupToAdf` and `jiraWikiToAdf`, short of five of seven.
The reader's name is the maintainer's to pick before item 195: the readers split four to three
between `jiraWikiMarkupToAdf` and `jiraWikiToAdf`, short of the five of seven that settle it
(`AGENTS.md` §7). The pick lands in this entry.
## Jira wiki markup spellings the help leaves open are a writer panel's picks ## Jira wiki markup spellings the help leaves open are a writer panel's picks
2026-11-16, a writer panel. Goal 11. Valid while a live Jira site renders each pick; the ones its 2026-11-16, a writer panel. Goal 11. Valid while a live Jira site renders each pick. The picks the
help does not show, `{note}`, a link's title, an image's `alt`, `\\` inside a cell and help doesn't show at all, `{note}`, a link's title, an image's `alt`, `\\` inside a cell,
`[~accountid:…]`, wait for the maintainer's check there. Lands with `spec/wiki.md`. `[~accountid:<id>]` and `+x+` as underline, wait for the maintainer's check on a live site. Lands
with `spec/wiki.md`.
Atlassian's text formatting notation help is the source for every spelling it shows. For the nine Atlassian's text formatting notation help is the source for every spelling it shows. Nine
it leaves open, seven fresh-context readers, seated as wiki-markup authors, each wrote their own spellings it leaves open went to seven fresh-context readers, seated as wiki-markup authors. Each
spelling before picking among shuffled candidates, with no rationale and nothing saying what is wrote their own spelling before picking among shuffled candidates, with no rationale and nothing
implemented. Seven agreed on a one-paragraph blockquote as `bq. `, any other as `{quote}`, a note saying what is implemented. Seven agreed on a one-paragraph blockquote as `bq. `, any other as
panel as `{note}`, underline as `+x+`, a mention as `[~accountid:5b10ac8d82e05b22cc7d4ef5]` and a `{quote}`, a note panel as `{note}`, underline as `+x+`, a mention as `[~accountid:<id>]` and a
cell's two paragraphs as `\\`. Six picked `{noformat}` over `{code:none}` for a code block with no cell's two paragraphs as `\\`. Six picked `{noformat}` over `{code:none}` for a code block with no
language, five `[text|url|title]` over dropping the title, five `alt=text` over `alt="text"`. The language, five `[text|url|title]` over dropping the title, and five `alt=text` over `alt="text"`.
first three seats read the brief's first 60 lines, which held a few of its first question's The first three readers saw a few of the first question's candidates among the brief's opening
candidates; the last four read 55. lines, before they wrote their own; the last four did not.
## A plain wiki spelling stands for the attributes Jira's editor writes, and any other attribute rides the carry
2026-11-16, the implementer of item 192, pending the maintainer's confirmation. Goals 1, 6 and 11.
Valid while Jira's editor writes these defaults.
Real Jira documents hold attributes that wiki markup can't spell: `order` 1 on every ordered list,
`accessLevel` `""` on every mention, `isNumberColumnEnabled` `false` and `layout` `default` on
every table, `layout` `center` on `mediaSingle`, `language` `""` on a code block. A plain spelling
stands for exactly those values and the reader writes them, so a Jira-authored document writes as
wiki markup, not as JSON. Any other value, `localId` and a mention's `text` among them, rides the
carry: the lossless writer keeps each attribute (`docs/decisions.md` §Ids stay site-local), and the
lossy writer drops it. `[~name]` reads as text, not as a mention with `id` `name`, since Jira Cloud
names a user by account id and the writer would otherwise write a different account back.
The maintainer is asked whether the lossless writer may drop a mention's `text` and any `localId`,
which would let more of a real document stay plain.
## `htmlToAdf` reads any HTML, with no option and no second call ## `htmlToAdf` reads any HTML, with no option and no second call
+70 -47
View File
@@ -1,33 +1,32 @@
# Jira wiki markup # Jira wiki markup
The wiki markup the lossless writer writes, the lossy writer writes and the reader reads, per node What `adfToLosslessJiraWiki`, `adfToLossyJiraWiki` and the Jira wiki markup reader do with each ADF
and mark. Its source is Atlassian's "Text Formatting Notation Help", which every Jira site serves at node and mark. Each table's middle column is what both writers write, and the last is what the
`/secure/WikiRendererHelpAction.jspa?section=all`; a spelling the help does not show is settled in reader reads; "The lossy writer" says where the lossy writer differs. The source is Atlassian's
`docs/decisions.md` §Jira wiki markup spellings the help leaves open are a writer panel's picks. The "Text Formatting Notation Help", which Jira serves at `/secure/WikiRendererHelpAction.jspa?section=all`.
carry is in `docs/decisions.md` §Jira wiki markup carries what it cannot spell in Jira's `{adf}` A spelling the help doesn't show is a writer panel's pick, per `docs/decisions.md` §Jira wiki
macro, and a lossy writer keeps only its content. The written form is contract markup spellings the help leaves open are a writer panel's picks. The written form is contract
(`docs/decisions.md` §The formats are API). (`docs/decisions.md` §The formats are API).
## The carry ## The carry
The lossless writer spells a node or mark wiki markup has no spelling for as Jira's own `{adf}` Wiki markup has no spelling for some nodes, marks and attributes. The lossless writer writes each
macro around ADF JSON: such node as Jira's own `{adf}` macro around the node's ADF JSON, per `docs/decisions.md` §Jira wiki
markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its
content:
- A block node: `{adf:display=block}`, a line feed, the node's JSON, a line feed, `{adf}`. - A block node: `{adf:display=block}`, a line feed, the JSON, a line feed, `{adf}`.
- An inline node, or a run of inline nodes under a mark wiki markup cannot spell: - An inline node, or the run of inline nodes under a mark with no spelling, as an array:
`{adf:display=inline}`, the JSON of the node, or the array of the run's nodes, `{adf}`. `{adf:display=inline}`, the JSON, `{adf}`.
The JSON is compact, and a `{` inside a string is `\u007b`, so the closing `{adf}` stands nowhere The JSON is compact with its keys sorted, as `spec/flavour.md` writes the markdown carry's, and a
else. A node rides the carry where its type, an attribute or a mark has no spelling in the tables `{` inside a string is `{`, so the closing `{adf}` is the only one the text holds.
below, or where its content holds a node that does. The carry holds the nearest block or inline node
that wiki markup can hold in its parent: a `listItem` and a `tableRow` cannot stand alone, so their
list or table rides it.
The lossy writer writes no `{adf}`. Where the lossless writer carries a node, the lossy writer keeps A node rides the carry when it, one of its attributes or one of its marks has no spelling below. It
what a reader of the rendered document sees, as `adfToPortableMarkdown` does (README §Portable also rides when it holds a block or inline node that rides, except that a node that rides inside a
markdown): the node's text, link targets and titles, its blocks where it holds some, and nothing for paragraph stands on its own there, in the paragraph's text. A block that rides inside a list item or
a `placeholder`. A mark the marks table does not spell drops, keeping its text. The lossy writer a table cell makes the list or the table ride instead, since wiki markup can't hold a block macro
also writes a table cell's blocks parted by `\\`. there. Any `localId` rides, since `docs/decisions.md` §Ids stay site-local keeps ids in attributes.
## Blocks ## Blocks
@@ -36,47 +35,71 @@ string.
| ADF | Wiki markup | Reader | | ADF | Wiki markup | Reader |
| --- | --- | --- | | --- | --- | --- |
| `paragraph` | its inline content | the same; a line feed inside it is a `hardBreak`, as Jira renders it | | `blockquote` holding one paragraph | `bq. `, the paragraph | the same |
| `heading`, `level` 1 to 6 | `h1. ` to `h6. ` | the same |
| `blockquote` of one paragraph | `bq. `, the paragraph | the same |
| `blockquote`, any other | `{quote}`, a line feed, its blocks, a line feed, `{quote}` | the same | | `blockquote`, any other | `{quote}`, a line feed, its blocks, a line feed, `{quote}` | the same |
| `bulletList`, `orderedList` | `* ` and `# `, one more mark per level, mixed as `#* ` and `*# `; an item holds a paragraph, then lists | also `- ` items, as `* ` | | `bulletList`, `orderedList` of `order` 1 or none, its items each a paragraph then lists | `* ` and `# `, one more character per level, nested lists mixed as `#* ` and `*# ` | the same, and `- ` items as `* `; an `orderedList` reads `order` 1 |
| `codeBlock` with a `language` the help lists, one text node | `{code:java}`, a line feed, its text, a line feed, `{code}` | `{code}` reads `language` `java`, the help's default | | `codeBlock` with a `language` named below, or none, holding one text node | `{code:<language>}`, a line feed, the text, a line feed, `{code}`; with none, `{noformat}`, the text, `{noformat}` the same way | the same; `{code}` reads `language` `java`; `title`, `borderStyle` and the other panel parameters drop |
| `codeBlock` with no `language`, one text node | `{noformat}`, a line feed, its text, a line feed, `{noformat}` | the same | | `heading` | `h1. ` to `h6. ` by `level` | the same |
| `panel` of `panelType` `info`, `note`, `tip`, `warning` | `{info}`, `{note}`, `{tip}`, `{warning}`, a line feed, its blocks, a line feed, the same macro | the same; a `title` parameter reads as the panel's first paragraph in `strong` | | `mediaSingle` of `layout` `center` or none, holding one external `media` and no caption | `!<url>!`, or `!<url>\|alt=<alt>!` where `alt` holds none of `!`, `\|` and `,` | the same, reading `layout` `center`; `thumbnail`, `align` and the other parameters drop |
| `panel` of `panelType` `info`, `note`, `tip` or `warning` | the macro of that name, a line feed, its blocks, a line feed, the macro | the same; a `title` parameter reads as the panel's first paragraph in `strong`; `{panel}` reads as `info` |
| `paragraph` holding content | its inline content | the same; a line feed in it reads as a `hardBreak`, as Jira renders it |
| `rule` | `----` | the same | | `rule` | `----` | the same |
| `table`, each cell one paragraph, a header row only first | `\|\|head\|\|`, then `\|cell\|` rows | the same | | `table` of plain rows, each cell holding one paragraph | per cell, `\|\|` for a `tableHeader` and `\|` for a `tableCell`, then its paragraph, the row closed by the last cell's delimiter; an empty paragraph as a space | the same; a space-only cell reads as an empty paragraph; reads `isNumberColumnEnabled` `false` and `layout` `default` |
| `mediaSingle`, centered, uncaptioned, holding an external `media` | `!url!`; `!url\|alt=text!` where it holds an `alt` with none of `!`, `\|`, `,` | the same | | any other block node, including a `paragraph` holding no content or only whitespace, and a node of a type this version doesn't know | the carry | `{adf:display=block}` reads its node |
| any other block node, a node of a type this version does not know | the carry | `{adf:display=block}` reads its node |
A `codeBlock` named in the table has a `language` of `""`, none, or a name the help lists, compared
ignoring case and written as the help spells it: ActionScript, Ada, AppleScript, bash, C, C#, C++,
CSS, Erlang, Go, Groovy, Haskell, HTML, Java, JavaScript, JSON, Lua, Nyan, Objc, Perl, PHP, Python,
R, Ruby, Scala, SQL, Swift, VisualBasic, XML and YAML. Any other `language`, and a text holding
`{code}` or `{noformat}`, rides the carry.
A `mediaSingle` or `table` attribute other than the ones the table names rides the carry: so does a
`width`, a merged cell and a colour.
## Inline ## Inline
| ADF | Wiki markup | Reader | | ADF | Wiki markup | Reader |
| --- | --- | --- | | --- | --- | --- |
| `text` | its text, a character wiki markup would read as markup where it stands taking a backslash; where a backslash cannot protect it, the run rides the inline carry | `\X` reads X |
| `hardBreak` | `\\` | the same | | `hardBreak` | `\\` | the same |
| `mention` holding an `id` and no other attribute | `[~accountid:5b10ac8d82e05b22cc7d4ef5]` | the same; `[~name]` reads `id` `name` | | `mention` holding `id` and an empty or no `accessLevel` | `[~accountid:<id>]` | the same, reading `accessLevel` `""`; `[~name]` reads as text, since Jira Cloud names a user by account id |
| any other inline node | the inline carry | `{adf:display=inline}` reads its nodes; `:)` and `:(` read `emoji` `:slight_smile:` and `:slight_frown:` | | `text` | its text; a character wiki markup would read as markup where it stands takes a backslash, and a text no backslash protects, such as a URL Jira would link, rides the carry | `\X` reads `X`; a bare `http://` or `https://` address reads as a `link` |
| any other inline node | the carry | `{adf:display=inline}` reads its nodes; `:)` and `:(` read `emoji` `:slight_smile:` and `:slight_frown:` |
## Marks ## Marks
| ADF | Wiki markup | Reader | | ADF | Wiki markup | Reader |
| --- | --- | --- | | --- | --- | --- |
| `strong`, `em`, `strike`, `underline`, `code` | `*x*`, `_x_`, `-x-`, `+x+`, `{{x}}` | the same; `??x??` reads `em` | | `code`, `em`, `strike`, `strong`, `underline` | `{{x}}`, `_x_`, `-x-`, `*x*`, `+x+` | the same; `??x??` reads `em` |
| `link` holding `href` | `[<text>\|<href>]`, with `\|<title>` after the `href` where it holds a `title`; `[<href>]` where the text is the `href` | the same; `[#anchor]` and `[^name.ext]` read as `href` `#anchor` and `^name.ext` |
| `subsup` | `^x^` for `sup`, `~x~` for `sub` | the same | | `subsup` | `^x^` for `sup`, `~x~` for `sub` | the same |
| `textColor` | `{color:#336699}x{color}` | the same; `{color:red}` reads `#ff0000` | | `textColor` | `{color:<hex>}x{color}` | the same; a CSS colour name reads as its hex code, so `red` as `#ff0000` |
| `link` holding `href`, and `title` | `[text\|url]`, `[text\|url\|title]`; `[url]` where the text is the url | the same; `[#anchor]` and `[^name.ext]` read as targets `#anchor` and `^name.ext` | | any other mark | the carry around the marked run | `{adf:display=inline}` reads its run |
| any other mark | the inline carry around the marked run | `{adf:display=inline}` reads its run |
A mark wiki markup spells opens and closes beside a character that bounds it. A run whose edge A mark's delimiters sit beside whitespace, punctuation or the line's edge, and the run's first and
touches a word character, or whose delimiters the reader would read another way, rides the inline last characters are not whitespace. A run where either fails rides the carry.
carry.
## The lossy writer
The lossy writer writes no `{adf}`. It writes the plain spellings above, and for what the lossless
writer carries it keeps the content, as `docs/decisions.md` §Plain text is blocks a blank line apart
says `adfToPlainText` does, in wiki markup:
- An attribute with no spelling drops. A node whose type has none is its text, or its blocks where
it holds some.
- A `panel` of another type is `{panel}`. An `expand` is its title as a `*strong*` paragraph, then
its body. A task item is `* `, then `☑ ` or `☐ ` and its text. A `status`, `date` and `emoji` are
the text they show, and a `mention` that rides is its `text`.
- A `table` cell holding several blocks has them parted by `\\`; a `codeBlock` with a language the
help doesn't list is `{noformat}`, and one whose text holds `{code}` or `{noformat}` is a
paragraph of its lines parted by `\\`.
- A stored `media` is its `alt`, else `[image]`.
- A mark with no spelling drops, keeping its text.
## What only the reader reads ## What only the reader reads
- `{anchor:name}` reads as nothing: no ADF node holds a bookmark. Each of these has no ADF counterpart, so the reader keeps the text where there is some:
- `{panel}` reads as a `panel` of `panelType` `info`, as the table says of a title; its colours and
border drop. - `{anchor:name}` reads as nothing, since no ADF node holds a bookmark.
- `!name.ext!` reads as text: no ADF node holds an attachment by name. - `!name.ext!` reads as its text: no ADF node holds an attachment by name.
- `---` and `--` read as `—` and `–`; `[file:///c:/temp/foo.txt]` reads as a `link`. - `---` and `--` read as `—` and `–`.
- A smiley other than `:)` and `:(` reads as text. - A smiley other than `:)` and `:(` reads as text: the help names no ADF `emoji` for it.
+5
View File
@@ -75,6 +75,11 @@ lossless writer does, except where that writer would use the `{adf}` macro.
A hand-written reader, as `htmlToAdf` is. Ships with the property that what the lossless writer of A hand-written reader, as `htmlToAdf` is. Ships with the property that what the lossless writer of
item 193 writes reads back deep-equal, and with refusals whose codes come from the closed list. item 193 writes reads back deep-equal, and with refusals whose codes come from the closed list.
The reader's name waits for the maintainer: the developer panel split four to three between
`jiraWikiMarkupToAdf` and `jiraWikiToAdf` (`docs/decisions.md` §Jira wiki markup's writers are
`adfToLosslessJiraWiki` and `adfToLossyJiraWiki`, two calls with no option). Name nothing public
until the pick lands in that entry.
### 196. Document the wiki calls in the README, with a row comparing them with Atlassian's `WikiMarkupTransformer`. ### 196. Document the wiki calls in the README, with a row comparing them with Atlassian's `WikiMarkupTransformer`.
A Quick start section per direction, the calls table and the guarantees. The comparison tables A Quick start section per direction, the calls table and the guarantees. The comparison tables