diff --git a/spec/wiki.md b/spec/wiki.md index a17bc99..6f95b30 100644 --- a/spec/wiki.md +++ b/spec/wiki.md @@ -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:]` | 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` | | --- | --- | --- | diff --git a/todo.md b/todo.md index 6a64b5b..0fa1bb1 100644 --- a/todo.md +++ b/todo.md @@ -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