mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-21 15:42:58 +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:
+47
-46
@@ -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).
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user