3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-20 23:25:43 +01:00

Answer prose round 1: 0 🔴, 13 🟡 (0 misread); state the overlap and the table question plainly, and fix the report's citations

This commit is contained in:
2026-11-09 09:43:14 +01:00
committed by Lillem4n
parent 927a245d5e
commit 7684643e6b
2 changed files with 52 additions and 50 deletions
+47 -46
View File
@@ -1,11 +1,11 @@
# `kovetskiy/mark` compared with this package # `kovetskiy/mark` compared with this package
Read and run on 2026-11-09 at `mark` v17.0.0 (`eacff19`): its README, the nine pages under its On 2026-11-09, at `mark` v17.0.0 (`eacff19`), read: its README, the nine pages under its `docs/`,
`docs/`, `AGENTS.md`, `go.mod`, the issue search and the storage-format calls in its source. Run: the `AGENTS.md`, `go.mod`, its issue tracker's search and the storage-format calls in its source. Run:
program, built in a `golang:1.27.3` container, with `publish --compile-only` and no network, on 14 the program, built in a `golang:1.27.3` container, with `publish --compile-only` and no network, on
fixtures from `corpus/round-trip/` and on one file of its own syntax. Only read: everything that 14 fixtures from `corpus/round-trip/` and on one file of its own syntax. Not run, only read: all
needs a Confluence account (publishing, page lookup, link resolution, attachments, labels, `mark that needs a Confluence account (publishing, page lookup, link resolution, attachments, labels,
export`). `mark export`).
## What it is ## What it is
@@ -16,70 +16,71 @@ back as markdown.
## Which format ## Which format
Not ADF. It parses markdown with goldmark and writes Confluence **storage format**, an XML dialect Not ADF. It parses markdown with goldmark and writes Confluence **storage format**, an XML dialect
(`ac:structured-macro`, `ac:task-list`, `<time datetime>`); the source holds no `atlas_doc_format` (`ac:structured-macro`, `ac:task-list`, `<time datetime>`). The source holds no `atlas_doc_format`
and sends every body as `"representation": "storage"`. Confluence's editor turns that into ADF and sends every body as `"representation": "storage"`, so `mark` never sees ADF.
itself, so mark never sees ADF.
It reads a page back only through `mark export`, from storage format, and writes storage format it It reads a page back only through `mark export`, from storage format. Storage format it has no
has no markdown for into the markdown as it is, much as the lossless flavour's carry holds a node markdown for stays in the exported markdown as it is, much as the lossless flavour's carry holds a
(`docs/export.md` §What stays storage format). Its list of what does not come back the same is node (`docs/export.md` in `mark`'s repo, §What stays storage format). Its list of what does not
the same kind as ours. come back the same from a publish after an export is like our list of exceptions under the README's
[The guarantees](../README.md#the-guarantees).
## How its spellings differ from ours ## How its spellings differ from ours
Each row ran through `mark` and through `commonMarkToAdf`, `losslessMarkdownToAdf` and Each row ran through `mark` and through `commonMarkToAdf`, `losslessMarkdownToAdf` and
`portableMarkdownToAdf` of v0.3.1. `portableMarkdownToAdf` of `@larvit/adf-codec` v0.3.1.
| Confluence feature | `mark` spells | This package | Difference | | Confluence feature | `mark` spells | This package | Difference |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Info, tip, note and warning boxes | `> [!NOTE]`, `> Note:`, `!!! note` | `portableMarkdownToAdf` reads `> [!NOTE]` as a `panel`; the lossless flavour spells `!adf:panel warning` | `[!IMPORTANT]`: blue info box in `mark`, `note` panel (purple, as on GitHub) here. `NOTE`, `TIP`, `WARNING` and `CAUTION` give the same box in both (`mark`'s note and warning boxes are ADF's `warning` and `error`). A colon marker and `!!! note` stay a quote and a paragraph here | | Info, tip, note and warning boxes | `> [!NOTE]`, `> Note:`, `!!! note` | `portableMarkdownToAdf` reads `> [!NOTE]` as a `panel`; the lossless flavour spells `!adf:panel warning` | `[!IMPORTANT]`: blue info box in `mark`, `note` panel (purple, as on GitHub) here. `NOTE`, `TIP`, `WARNING` and `CAUTION` give the same box in both: Confluence's note and warning macros are ADF's `warning` and `error` panels. A quote opening `Note:` (a colon marker) and `!!! note` stay a quote and a paragraph here |
| Expand | `<details><summary>` | `!adf:expand {title="…"}` | `htmlToAdf` and the markdown readers refuse `<details>` as `unmappable-html` until items 137 and 138 | | Expand | `<details><summary>` | `!adf:expand {title="…"}` | `htmlToAdf` and the markdown readers refuse `<details>` as `unmappable-html` until items 137 and 138 |
| Task list | `- [x]` | `- [x]` in the portable flavour; `!adf:taskList` in the lossless one | the same spelling; `commonMarkToAdf` reads a bullet list, as CommonMark has no task | | Task list | `- [x]` | `- [x]` in the portable flavour; `!adf:taskList` in the lossless one | the same spelling; `commonMarkToAdf` reads a bullet list, as CommonMark has no task list |
| Date | `@date(2026-07-27)`, `<time datetime>` (behind `--features date`) | `!adf:date{timestamp=…}`; `<time class="adf-date">` in HTML | `<time datetime>` is refused as `unmappable-html`; `@date()` is text here (`docs/decisions.md` §Names stay text) | | Date | `@date(2026-07-27)`, `<time datetime>` (behind `--features date`) | `!adf:date{timestamp=…}`; `<time class="adf-date">` in HTML | `<time datetime>` is refused as `unmappable-html`; `@date()` is text here (`docs/decisions.md` §Names stay text) |
| Emoji | `:tada:` (behind `--features emoji`) | `!adf:emoji[🎉]{…}` | text here, same entry | | Emoji | `:tada:` (behind `--features emoji`) | `!adf:emoji[🎉]{…}` | `:tada:` is text here, same entry |
| Link to a page | `[text](ac:Title)`, `./other.md` | a link with that destination | `mark` resolves it with Confluence; here it is a plain link | | Link to a page | `[text](ac:Title)`, `./other.md` | a link with that destination | `mark` resolves it with Confluence; here it is a plain link |
| Status, Jira ticket, table of contents | a macro template: `<!-- Macro: … -->`, `ac:status`, `ac:jira:ticket` | `!adf:status[…]{color=…}`, `!adf:inlineCard{url=…}` | its templates are Go text templates writing storage format; ours are node directives | | Status, Jira ticket | a macro template: `<!-- Macro: … -->`, `ac:status`, `ac:jira:ticket` | `!adf:status[…]{color=…}`, `!adf:inlineCard{url=…}` | its templates are Go text templates writing storage format; ours are node directives |
| Mentions, panels with custom colours, media | storage format written by hand, or a template | `!adf:mention`, `!adf:panel custom`, `!adf:mediaSingle` | none in `mark`'s markdown | | Mentions, panels with custom colours, media | storage format written by hand, or a template | `!adf:mention`, `!adf:panel custom`, `!adf:mediaSingle` | none in `mark`'s markdown |
What `mark` spells and ADF has no node for, so nothing here corresponds: page metadata in header What `mark` spells and ADF holds no node for, so nothing here corresponds: page metadata in header
comments or YAML front matter (`Space`, `Parent`, `Title`, `Label`, `Attachment`, `Layout`, comments or YAML front matter (`Space`, `Parent`, `Title`, `Label`, `Attachment`, `Layout`,
restrictions, content properties), `<!-- Include: -->` and `<!-- Macro: -->`, attachments, restrictions, content properties), `<!-- Include: -->`, `<!-- Macro: -->` as a mechanism, the table
footnotes, definition lists, math, and Mermaid, D2 and PlantUML diagrams drawn into images. of contents macro, attachments, footnotes, definition lists, math, and Mermaid, D2 and PlantUML
diagrams drawn into images.
Our directives written to `mark` come out as text: every `!adf:` line of the 14 fixtures is Our directives written to `mark` come out as text: every `!adf:` line of the 14 fixtures is
published as a paragraph holding it. `commonMarkToAdf` refuses a `mark` document that opens with published as a paragraph holding it. `commonMarkToAdf` refuses a `mark` document that opens with
`<!-- Space: DOCS -->`, as `unmappable-html`, because a comment is content ADF cannot hold `<!-- Space: DOCS -->` as `unmappable-html`, and refuses `<!-- Include: -->` the same way, because
(`docs/decisions.md` §Foreign HTML sorts three ways); so does `<!-- Include: -->`. Neither is a a comment is content ADF cannot hold (`docs/decisions.md` §Foreign HTML sorts three ways). Both
defect against that entry. refusals follow that entry.
## Which the audience would expect ## What the audience would expect
`mark`'s spellings are the ones the README's people already write: GitHub alerts, `<details>`, `mark`'s spellings for boxes, expands and tasks are ones the README's people already write: GitHub
`- [x]`. Ours agree for alerts and tasks in the portable flavour, and will for `<details>` once alerts, `<details>`, `- [x]`. Ours agree for alerts and tasks in the portable flavour, and will for
items 137 and 138 land. The lossless flavour's `!adf:` directives are for what no `<details>` once items 137 and 138 land. For mentions, custom panels and media `mark` spells
markdown spells, and `mark` spells none of those, so they never compete. The one divergence nothing, so the lossless flavour's directives meet no spelling of its. For a date, an emoji, a
that reads either way is `[!IMPORTANT]`; the README states ours (`README.md` § Portable markdown). status and a card `mark` does spell something (`@date()`, `:tada:`, a macro template), and which
spelling the audience would expect there is for a writer panel, not this report. The one divergence
in a shared spelling is `[!IMPORTANT]`, which `README.md` §Portable markdown states for ours.
## Overlap ## Overlap
Product managers, engineers and support agents who write markdown for Confluence are the README's The people who write markdown for Confluence are the README's second audience. `mark` serves them
second audience. `mark` serves them as a publishing pipeline for a repository of documents; this with a publishing pipeline for a repository of documents; this package serves the four developer
package serves the four developer personas who embed a converter. The bot persona (generated personas who embed a converter. Of those, the bot persona (generated markdown to ADF) is closest:
markdown to ADF) is the one overlap: both turn markdown into Confluence content, but `mark` needs both tools turn markdown into Confluence content. `mark` needs an account and the REST API; this
an account and the REST API, this package takes none (Goal 8). A user of `mark` who needs ADF can package needs neither (Goal 8).
publish with `mark` and fetch the page as ADF through the Confluence REST API, which converts
storage format to ADF; a user of this package who needs storage format has to go to that same API A user of `mark` who needs ADF can fetch the page as ADF through the Confluence REST API, which
(`README.md` § Other ADF converters). converts storage format to ADF. A user of this package who needs storage format goes to that same
API (`README.md` §Other ADF converters).
## Does it belong in the comparison table ## Does it belong in the comparison table
Neither table fits. The first lists npm packages that run in Node and convert ADF to or from Neither table fits. The first lists npm packages that run in Node and convert ADF to or from
markdown; the second lists converters this comparison does not run, and every row of it converts markdown. The second lists converters the comparison does not run, and every library in it converts
ADF. `mark` is a Go program that never touches ADF. Filed as item 177, a question to the maintainer, with the ADF. `mark` is a Go program that never touches ADF. Item 177 asks the maintainer: leave it out, or
options: leave it out, or add a row to the second table saying it converts markdown to storage add a row to the second table saying it converts markdown to storage format and not ADF.
format and not ADF.
## Filed No spelling changes follow: `[!IMPORTANT]` is the README's choice to reopen, not a defect, and only
a writer panel changes a spelling (`AGENTS.md` §7).
Only item 177. The differences do not ask for a change to a spelling: `[!IMPORTANT]` is
an entry's choice to reopen, not a defect, and only a writer panel changes one (`AGENTS.md` §7).
+5 -4
View File
@@ -65,11 +65,12 @@ files, with its `ci.sh` probe, extends the decision.
### 177. Decide whether `kovetskiy/mark`, a Go program that writes Confluence storage format and never touches ADF, gets a row in the README's second "Other ADF converters" table, and record the answer in §The comparison table lists every converter that starts and converts. ### 177. Decide whether `kovetskiy/mark`, a Go program that writes Confluence storage format and never touches ADF, gets a row in the README's second "Other ADF converters" table, and record the answer in §The comparison table lists every converter that starts and converts.
The gap: §The comparison table lists every converter that starts and converts covers converters of The gap: the decision entry "The comparison table lists every converter that starts and converts"
settles which npm packages and which other-ecosystem libraries are listed, and all of them convert
ADF. The first table lists npm packages that run in Node and convert ADF to or from markdown; the ADF. The first table lists npm packages that run in Node and convert ADF to or from markdown; the
second lists converters the comparison does not run, and every row of it converts ADF. `mark` second lists converters the comparison does not run, and every library in it converts ADF. `mark`
converts markdown to storage format only (`docs/kovetskiy-mark.md` § Does it belong in the converts markdown to storage format only (`docs/kovetskiy-mark.md`, "Does it belong in the
comparison table). The options: leave it out, or add a row saying it converts markdown to storage comparison table"). The options: leave it out, or add a row saying it converts markdown to storage
format and not ADF. format and not ADF.
Candidate sentence for the entry: "A converter that never reads or writes ADF, such as one writing Candidate sentence for the entry: "A converter that never reads or writes ADF, such as one writing