mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-21 15:42:58 +01:00
Answer prose round 1: the comments and test name say what ends a list, the README says because, the changelog leads with the rename and gives the definition's trigger, and items 56 and 98 state their claims plainly
This commit is contained in:
+11
-10
@@ -2,12 +2,6 @@
|
|||||||
|
|
||||||
## Unreleased
|
## Unreleased
|
||||||
|
|
||||||
- **Breaking:** a list whose bullet character or ordered delimiter changes reads as two lists, as
|
|
||||||
CommonMark reads it: `- a` then `* b`, `1. a` then `1) b`. `adfToLosslessMarkdown` gives a list
|
|
||||||
right after one of its kind the other marker, `* ` or `1)`, in place of the `::listBreak`
|
|
||||||
separator. Convert stored markdown per `MIGRATION.md`.
|
|
||||||
- **Breaking:** a link reference definition between two list items ends the list, as CommonMark
|
|
||||||
reads it: `- a`, `[r]: /u`, `- b` read as two lists, where `0.1.0` read one; see `MIGRATION.md`.
|
|
||||||
- **Breaking:** each call names the markdown it reads or writes. `adfToMarkdown` and `markdownToAdf`
|
- **Breaking:** each call names the markdown it reads or writes. `adfToMarkdown` and `markdownToAdf`
|
||||||
are now `adfToLosslessMarkdown` and `losslessMarkdownToAdf`. A bot's or a model's markdown reads
|
are now `adfToLosslessMarkdown` and `losslessMarkdownToAdf`. A bot's or a model's markdown reads
|
||||||
in `portableMarkdownToAdf`, and markdown known to be strict CommonMark in the new
|
in `portableMarkdownToAdf`, and markdown known to be strict CommonMark in the new
|
||||||
@@ -58,11 +52,18 @@
|
|||||||
`losslessMarkdownToAdf` refuses a directive mark wrapping only hard breaks as
|
`losslessMarkdownToAdf` refuses a directive mark wrapping only hard breaks as
|
||||||
`unsupported-node-shape`. `adfToLosslessMarkdown` writes a hard break holding marks as
|
`unsupported-node-shape`. `adfToLosslessMarkdown` writes a hard break holding marks as
|
||||||
`!adf:carry{json="…"}`. See `MIGRATION.md`.
|
`!adf:carry{json="…"}`. See `MIGRATION.md`.
|
||||||
|
- **Breaking:** a list whose bullet character or ordered delimiter changes reads as two lists, as
|
||||||
|
CommonMark reads it: `- a` then `* b`, `1. a` then `1) b`. `adfToLosslessMarkdown` gives a list
|
||||||
|
right after one of its kind the other marker, `* ` or `1)`, in place of the `::listBreak`
|
||||||
|
separator. Convert stored markdown per `MIGRATION.md`.
|
||||||
|
- **Breaking:** a link reference definition between two list items, after a blank line and at the
|
||||||
|
list's own indentation, ends the list, as CommonMark reads it; `0.1.0` read one list. See
|
||||||
|
`MIGRATION.md`.
|
||||||
- Fix the time `adfToLosslessMarkdown` and `adfToPortableMarkdown` take on text holding a long run of
|
- Fix the time `adfToLosslessMarkdown` and `adfToPortableMarkdown` take on text holding a long run of
|
||||||
`*`, `_`, `~` or backticks, or a heading ending in a long run of `#`: it is linear in the run, and
|
`*`, `_`, `~` or backticks, or a heading ending in a long run of `#`: the time is linear in the
|
||||||
a run of 20000 `*` takes milliseconds where it took seconds.
|
run, and a run of 20000 `*` takes milliseconds where it took seconds.
|
||||||
- Fix the round-trip: `losslessMarkdownToAdf(adfToLosslessMarkdown(doc))` deep-equals `doc` as
|
- Fix the round-trip, so `losslessMarkdownToAdf(adfToLosslessMarkdown(doc))` deep-equals `doc` as
|
||||||
`JSON.parse` builds it: two adjacent text nodes CommonMark would read back as one are parted by
|
`JSON.parse` builds it. Two adjacent text nodes CommonMark would read back as one are parted by
|
||||||
`!adf:textBreak{}`, an empty `attrs`, `content` or `marks` is spelled `{attrs=empty}`,
|
`!adf:textBreak{}`, an empty `attrs`, `content` or `marks` is spelled `{attrs=empty}`,
|
||||||
`{content=empty}` or `{marks=empty}`, `-0` is spelled `-0`, and a `codeBlock` of several text
|
`{content=empty}` or `{marks=empty}`, `-0` is spelled `-0`, and a `codeBlock` of several text
|
||||||
nodes is a fence per node. A `codeBlock` holding other than plain text nodes rides the block
|
nodes is a fence per node. A `codeBlock` holding other than plain text nodes rides the block
|
||||||
|
|||||||
@@ -239,8 +239,8 @@ Serves Goals 1, 4 and 5.
|
|||||||
without a delimiter row, is an error result; each can be kept literal (`spec/flavour.md`).
|
without a delimiter row, is an error result; each can be kept literal (`spec/flavour.md`).
|
||||||
- A document any reader built, written back with `adfToLosslessMarkdown`, takes the library's
|
- A document any reader built, written back with `adfToLosslessMarkdown`, takes the library's
|
||||||
canonical spelling, which round-trips byte-identically.
|
canonical spelling, which round-trips byte-identically.
|
||||||
- These CommonMark spellings parse without an error and build a document the reference
|
- These CommonMark spellings parse without an error but build a document the reference
|
||||||
implementation renders differently, where ADF holds no node for what it renders:
|
implementation renders differently, because ADF holds no node for what the reference renders:
|
||||||
- An empty link text reads as its destination, `[](/url)` as `/url` linked to `/url`, and `[]()`
|
- An empty link text reads as its destination, `[](/url)` as `/url` linked to `/url`, and `[]()`
|
||||||
as nothing. A link text holding only hard breaks reads the same, followed by its hard breaks.
|
as nothing. A link text holding only hard breaks reads the same, followed by its hard breaks.
|
||||||
- An image reads as an image only alone in its paragraph. Anywhere else — beside other text, in
|
- An image reads as an image only alone in its paragraph. Anywhere else — beside other text, in
|
||||||
@@ -253,12 +253,12 @@ Serves Goals 1, 4 and 5.
|
|||||||
- An image's title becomes its caption when the image stays an image, and its link's title when
|
- An image's title becomes its caption when the image stays an image, and its link's title when
|
||||||
it becomes linked alt text. Inside another link, the title is dropped.
|
it becomes linked alt text. Inside another link, the title is dropped.
|
||||||
|
|
||||||
And these, for other reasons: a shortcut reference matching its definition only under Unicode case folding stays
|
And these, for other reasons: a shortcut reference matching its definition only under Unicode case
|
||||||
unresolved, and a link whose text holds an autolink keeps the inner link and leaves the outer
|
folding stays unresolved, and a link whose text holds an autolink keeps the inner link and leaves
|
||||||
brackets literal text, which the spec requires and the reference itself breaks, nesting one `<a>`
|
the outer brackets literal text, which the spec requires and the reference itself breaks, nesting
|
||||||
in the other. `corpus/commonmark-spec/exceptions.json` pins the spellings ADF holds no node for
|
one `<a>` in the other. `corpus/commonmark-spec/exceptions.json` marks each spelling ADF holds no
|
||||||
`node-model` where the suite reaches them, and the case-folded reference `pending`; the suite
|
node for as `node-model` where the suite has an example of it, and the case-folded reference as
|
||||||
holds no example of a link holding an autolink.
|
`pending`; the suite holds no example of a link holding an autolink.
|
||||||
- Not every document converts back: `adfToLosslessMarkdown` refuses a document nesting past 500
|
- Not every document converts back: `adfToLosslessMarkdown` refuses a document nesting past 500
|
||||||
levels, and the node shapes the `unsupported-node-shape` row lists. Show the refusal and keep the
|
levels, and the node shapes the `unsupported-node-shape` row lists. Show the refusal and keep the
|
||||||
document read-only; saving markdown you could not produce is the loss the round-trip exists to
|
document read-only; saving markdown you could not produce is the loss the round-trip exists to
|
||||||
|
|||||||
@@ -248,7 +248,7 @@ function openContainer(walk: Walk, start: ContainerStart): void {
|
|||||||
walk.stack.push({ blocks, indentation: start.indentation, kind: 'item', list })
|
walk.stack.push({ blocks, indentation: start.indentation, kind: 'item', list })
|
||||||
}
|
}
|
||||||
|
|
||||||
// An item opening after its list's last item closed, as an empty item a blank line ends does, continues that list.
|
// An empty item closes at the blank line after it, yet the next item continues its list unless endList ended it.
|
||||||
function openedList(walk: Walk, start: Extract<ContainerStart, { kind: 'item' }>): ListBlock {
|
function openedList(walk: Walk, start: Extract<ContainerStart, { kind: 'item' }>): ListBlock {
|
||||||
if (!start.fresh) return start.list
|
if (!start.fresh) return start.list
|
||||||
const blocks = currentBlocks(walk)
|
const blocks = currentBlocks(walk)
|
||||||
@@ -258,7 +258,7 @@ function openedList(walk: Walk, start: Extract<ContainerStart, { kind: 'item' }>
|
|||||||
return start.list
|
return start.list
|
||||||
}
|
}
|
||||||
|
|
||||||
// A paragraph of link reference definitions alone leaves no block, yet ends the list before it as any block does.
|
// A paragraph holding only link reference definitions leaves no block, yet ends the list before it as any block does.
|
||||||
function endList(walk: Walk): void {
|
function endList(walk: Walk): void {
|
||||||
const previous = currentBlocks(walk).at(-1)
|
const previous = currentBlocks(walk).at(-1)
|
||||||
if (isList(previous)) walk.endedLists.add(previous)
|
if (isList(previous)) walk.endedLists.add(previous)
|
||||||
|
|||||||
@@ -676,7 +676,7 @@ test('reads a bullet list, the marker width setting the continuation', () => {
|
|||||||
assert.deepEqual(content(losslessMarkdownToAdf('-\n\n Part.\n')), [bulletList(item()), paragraph('Part.')])
|
assert.deepEqual(content(losslessMarkdownToAdf('-\n\n Part.\n')), [bulletList(item()), paragraph('Part.')])
|
||||||
})
|
})
|
||||||
|
|
||||||
test('reads two lists a link reference definition parts as two lists, in every reader', () => {
|
test('ends a list at a link reference definition, in every reader', () => {
|
||||||
for (const read of [commonMarkToAdf, losslessMarkdownToAdf, portableMarkdownToAdf]) {
|
for (const read of [commonMarkToAdf, losslessMarkdownToAdf, portableMarkdownToAdf]) {
|
||||||
assert.deepEqual(content(read('- a\n\n[r]: /u\n\n- b\n')), [bulletList(item(paragraph('a'))), bulletList(item(paragraph('b')))])
|
assert.deepEqual(content(read('- a\n\n[r]: /u\n\n- b\n')), [bulletList(item(paragraph('a'))), bulletList(item(paragraph('b')))])
|
||||||
assert.deepEqual(content(read('- a\n\n[r]: /u\n- b\n')), [bulletList(item(paragraph('a'))), bulletList(item(paragraph('b')))])
|
assert.deepEqual(content(read('- a\n\n[r]: /u\n- b\n')), [bulletList(item(paragraph('a'))), bulletList(item(paragraph('b')))])
|
||||||
|
|||||||
@@ -150,8 +150,9 @@ three linear.
|
|||||||
each blank line, and `parseBlocks` holds no depth guard: `readBlocks` refuses past 500 levels only
|
each blank line, and `parseBlocks` holds no depth guard: `readBlocks` refuses past 500 levels only
|
||||||
after the walk. `'- '.repeat(n) + 'a\n' + '\n'.repeat(n)` took 675 ms at n = 5000, 2.7 s at 10000
|
after the walk. `'- '.repeat(n) + 'a\n' + '\n'.repeat(n)` took 675 ms at n = 5000, 2.7 s at 10000
|
||||||
and 10.7 s at 20000 (60 kB) before refusing as `unsupported-nesting-depth`. `docs/decisions.md`
|
and 10.7 s at 20000 (60 kB) before refusing as `unsupported-nesting-depth`. `docs/decisions.md`
|
||||||
§Cost fixes are measured, never timed calls the re-scan bounded by that guard; correct it with the
|
§Cost fixes are measured, never timed says the 500-level guard bounds `continuesContainer`'s
|
||||||
fix.
|
re-scan in depth; the guard runs only after the walk, so it bounds nothing. Correct that entry with
|
||||||
|
the fix.
|
||||||
|
|
||||||
### 7. Ship HTML: `adfToHtml`, `htmlToAdf`, and markdown to and from HTML composed through ADF, each call named by its flavour.
|
### 7. Ship HTML: `adfToHtml`, `htmlToAdf`, and markdown to and from HTML composed through ADF, each call named by its flavour.
|
||||||
|
|
||||||
@@ -353,10 +354,9 @@ quadratic in a run of blanks inside one leaf: a paragraph of `a`, 80 000 spaces,
|
|||||||
|
|
||||||
### 56. Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.
|
### 56. Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.
|
||||||
|
|
||||||
Technical principle "One owner per value": the `Walk` record passes through twelve functions that
|
Technical principle "One owner per value": the `Walk` record passes through functions that mutate it
|
||||||
mutate it and return `void`; `walk.leaf` alone is written in seven places, and `openedList` reads
|
and return `void`; `walk.leaf` alone is written in seven places, and `openedList` reads the
|
||||||
the `endedLists` that `closeLeaf` fills. `ContainerStack` in the
|
`endedLists` that `closeLeaf` fills. `ContainerStack` in the same file shows the shape to follow. `inline-content.ts`'s `Scan` has the same shape: about fifteen
|
||||||
same file shows the shape to follow. `inline-content.ts`'s `Scan` has the same shape: about fifteen
|
|
||||||
functions write `pending`, `pieces`, `deactivatedBefore` and `openingSpellableLink` and return
|
functions write `pending`, `pieces`, `deactivatedBefore` and `openingSpellableLink` and return
|
||||||
`void`, and `parseInlineContent` reads a flag `scanInline` leaves on it. The same shape recurs in
|
`void`, and `parseInlineContent` reads a flag `scanInline` leaves on it. The same shape recurs in
|
||||||
`mintTaskIds` (`portable/task-ids.ts`), which writes `attrs` on the document `readDocument` built;
|
`mintTaskIds` (`portable/task-ids.ts`), which writes `attrs` on the document `readDocument` built;
|
||||||
|
|||||||
Reference in New Issue
Block a user