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

Answer product-owner round 1: 0 🔴, 2 🟡 (0 misread); list what Jira keeps a backslash before in the text row, name the smiley a backslash cannot stop, and file the bold-label carry as item 199

This commit is contained in:
2026-11-17 03:22:07 +01:00
committed by Lillem4n
parent 8ae1b21508
commit 55f8675d6a
2 changed files with 30 additions and 13 deletions
+18 -12
View File
@@ -66,14 +66,14 @@ a `width`, a merged cell and a colour.
| --- | --- | --- |
| `hardBreak` | `\\` | the same |
| `mention` holding `id` and `accessLevel` `""`, and no other attribute, the `id` not empty and holding no whitespace or markup character | `[~accountid:<id>]` | the same, reading `accessLevel` `""`; `[~name]` reads as text, since Jira Cloud names a user by account id |
| `text` | its text, escaped as below | `\\` reads as a `hardBreak` before `\X` reads `X`; a bare `http://` or `https://` address reads as a `link` |
| `text` | its text, escaped as below | `\\` reads as a `hardBreak` before `\X` reads `X`, except that Jira keeps the backslash before `:`, `;`, `.`, `,`, a letter, a digit or another backslash; a bare `http://` or `https://` address reads as a `link` |
| any other inline node | the carry | `{adf:display=inline}` reads its node |
A character takes a backslash where wiki markup would read it as markup. Here a line's edge counts
as whitespace, and a node's edge inside the line as punctuation:
- `[`, `]`, `{`, `}` and `|`, always, except that a `|` in a table cell rides the carry, since an
escaped one still ends the cell.
- `[`, `]`, `{`, `}` and `|`, always. A text holding a `|` in a table cell rides the carry instead,
since an escaped `|` still ends the cell.
- `*`, `+`, `-`, `^`, `_` and `~`, unless a letter or digit stands on both sides, or whitespace
does.
- `?` before another `?`, and `!` before anything but whitespace.
@@ -82,13 +82,19 @@ as whitespace, and a node's edge inside the line as punctuation:
inside the line.
- At a line's start, `#`, `*` and `-`.
Jira keeps a backslash before `:`, `;`, a letter or a digit as text. So no backslash protects a
backslash, a line feed or a carriage return; `http://` or `https://` in any case, which Jira would
link; the `h` of `h1.` to `h6.` or the `b` of `bq.` at a line's start, in any case; `:D` and `:P`;
or a `:` or `;` ending a node inside the line, where the next node's spelling may close a smiley. A
text holding one rides the carry. So does a text that starts or ends its line with whitespace, and
a text whose marks are those of the text before it, which the reader would join. A `hardBreak` or
`mention` holding a mark rides too.
Jira keeps a backslash before `:`, `;`, `.`, `,`, a letter, a digit or another backslash as text.
So a backslash protects none of these, and a text holding one rides the carry:
- a backslash, a line feed or a carriage return;
- `http://` or `https://`, which Jira would link;
- the `h` of `h1.` to `h6.` or the `b` of `bq.` at a line's start, in any case;
- a smiley that reads and that no backslash before its `(` or closing `)` stops: `:D` and `:P`
where no letter or digit follows, and a `:` or `;` ending a node inside the line, where the next
node's spelling may close a smiley.
A text that starts or ends its line with whitespace rides the carry too, and so does a text whose
marks are those of the text before it, which the reader would join. A `hardBreak` or `mention`
holding a mark rides as well.
## Marks
@@ -132,8 +138,8 @@ The writers never write these, and the reader reads them as follows:
- `---` and `--` read as `—` and `–`.
- A smiley reads as the `emoji` Jira reads it as, wherever the next character is not a letter or a
digit and whatever comes before it: `x:)` and `f(x)` read, `a:Pb` and `:)x` don't, and a backslash
before its `(` or its closing `)` stops it: `\(y)` and `:\)` read as text. The `emoji`'s `text` is the character where its `id` is a code point, else its
`shortName`.
before its `(` or its closing `)` stops it: `\(y)` and `:\)` read as text. The `emoji`'s `text`
is the character where its `id` is a code point, else its `shortName`.
| Smiley | `shortName` | `id` |
| --- | --- | --- |
+12 -1
View File
@@ -6,7 +6,7 @@
`Bar = 0.1`
`Next ID = 199`
`Next ID = 200`
## Items
@@ -16,6 +16,7 @@
| 194 | 0.4.0 | | owner | **Write ADF as Jira wiki markup alone, dropping the form and keeping the content of what wiki markup cannot spell.** | 2 | 2 | 2 | 4 | 4 | 11 by 2 | 1.1 |
| 195 | 0.4.0 | | owner | **Read Jira wiki markup into ADF, `{adf}` macros included, as `spec/wiki.md` says.** | 4 | 1 | 2 | 5 | 8 | 11 by 5 | 0.3 |
| 196 | 0.4.0 | 194, 195 | owner | **Document the wiki calls in the README, with a row comparing them with Atlassian's `WikiMarkupTransformer`.** | 1 | 2 | 1 | 2 | 2 | 3 by 2, 11 by 1 | 3.6 |
| 199 | 0.4.0 | | | **Spell a text ending in `:` or `;` inside a line plainly where the next spelled character cannot close a smiley, as in `*Environment:* Chrome`.** | 2 | 1 | 1 | 2 | 3 | 6 by 2, 11 by 2 | 3.5 |
| 137 | 0.4.0 | | decision | **Read foreign HTML in `htmlToAdf` best effort, never refusing it, as `docs/decisions.md` §Foreign HTML reads best effort and is never refused states.** | 2 | 1 | 2 | 3 | 4 | 12 by 6 | 3.3 |
| 172 | 0.4.0 | | principle | **Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.** | 3 | 1 | 1 | 3 | 8 | code health by 2 | 0.5 |
| 107 | 0.4.0 | | decision | **Spell the block carry's JSON so its length stays linear in the node's JSON.** | 3 | 1 | 3 | 5 | 5 | | 0.0 |
@@ -101,6 +102,16 @@ Touches:
- `README.md`: `## Main functionality`, `## Quick start`, `## Other ADF converters`, `## The calls`, `### The error shape` (small), `## The guarantees`, `## Everything exported`
- `converter-comparison/compare.mjs`: lines 67-108 (small)
### 199. Spell a text ending in `:` or `;` inside a line plainly where the next spelled character cannot close a smiley, as in `*Environment:* Chrome`.
Item 198's product-owner review found that `escapedText` carries any text ending in `:` or `;` inside a line, since the next node's spelling may close a smiley. The closing delimiter of a mark group (`*` after `Environment:`) cannot, so a bold label comes out as `{adf}` JSON where plain `*Environment:*` reads the same. `atom` doesn't know the next spelled character; `groupSpelling` does.
Touches:
- `src/wiki/emit/inline-line.ts`: `atom`, `groupSpelling`
- `src/wiki/emit/text-escaping.ts`: `escapedText`, `smileyStops`
- `spec/wiki.md`: Inline
- `src/wiki/emit/adf-to-jira-wiki.test.ts` (small)
### 137. Read foreign HTML in `htmlToAdf` best effort, never refusing it, as `docs/decisions.md` §Foreign HTML reads best effort and is never refused states.
Reading HTML from emails, CMSs and editors is the most asked need on the Atlassian developer