Document the preserving writer, in one page and two languages - #6
Merged
Conversation
One page under how-to, carrying parity("lossless-round-trip") after the intro.
The macro renders nothing now that both sides are complete, which is the right
answer: there is no longer a difference to report.
The section that would otherwise be missing is the last one. The text format
preserves per object and the object notation is all or nothing, in BOTH
languages, because it is a property of the format rather than a difference
between the libraries. A reader who knows the text format's terms would assume
them, so the page states the difference next to the code rather than leaving it
to be discovered.
The page also states what "the same file" means: reproduction is defined against
the text a read was GIVEN, not against a file's bytes, and the two defects that
live on the other side of that line are named.
`check-vendored` fails until idfkit-js publishes docs-2026.3. The TypeScript
snippets here were vendored from that tag in a local checkout, which the sync
tool permits under --from-sibling and correctly says is not evidence about the
pinned tag.
The snippets were identical; the TypeDoc reference was built from a working tree that predated the last two commits on the branch. This is the one the tag carries, fetched rather than built here.
samuelduchesne
marked this pull request as ready for review
September 6, 2026 17:28
Contributor
|
Docs preview for this PR is available at: Changed pages: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft: blocked on
docs-2026.3being published from idfkit-js, which is blocked on idfkit/idfkit-js#45.check-vendoredfails until then, and correctly: the TypeScript snippets here were vendored withsync_js_artifacts.py --from-sibling, which the tool permits and correctly says "is not evidence about the pinned tag".One page under How-to, carrying
parity("lossless-round-trip")after the intro. The macro renders nothing now that both sides are complete, which is the right answer: there is no longer a difference to report.The section that would otherwise be missing
The text format preserves per object; the object notation is all or nothing — in both languages, because it is a property of the format rather than a difference between the libraries. A reader who knows the text format's terms would assume them, so the page states the difference next to the code rather than leaving it to be discovered.
The page also says what "the same file" means: reproduction is defined against the text a read was given, not against a file's bytes, and it names the two defects that live on the other side of that line — the TypeScript reader refusing a byte-order mark, and Python's
save_idftranslating line endings because it opens its destination withoutnewline="".Verified locally
The page builds, both languages' snippets inline correctly, and
check_capability_declarations.pyaccepts it.make docs-testfails on this machine for a missinglibcairo, unrelated to the page: none of the 108 warnings it emits names it.[tool.idfkit.governance]moves togovernance-2026.14and[tool.idfkit.docs]todocs-2026.3.