Skip to content

Fold the files derived from a document beneath it in the viewer - #933

Merged
SimonCropp merged 1 commit into
mainfrom
paged-documents
Oct 4, 2026
Merged

SimonCropp merged 1 commit into
mainfrom
paged-documents

Conversation

@SimonCropp

Copy link
Copy Markdown
Member

A snapshot library that verifies a document often verifies what it computed from the document as well: a png and the text of each page, a csv per sheet. Each is a pending file of its own, so a reviewer accepts the document and then every file derived from it, even though the viewer's row for the document has already shown its pages and its text.

This lets a caller say that a pending file was derived from a pending source, and has the viewer fold derived files beneath the document they came from.

API

// The document first: what is derived from it names it
await DiffRunner.LaunchAsync(documentTempFile, documentTargetFile);

// A file computed from the document, named by the document's temp file
await DiffRunner.LaunchDerivedAsync(pageTempFile, pageTargetFile, documentTempFile, null);

// A file the document no longer produces
await DiffRunner.AddDerivedDeleteAsync(stalePageFile, documentTempFile);

Also LaunchDerived, LaunchDerivedForText, LaunchDerivedForTextAsync and AddDerivedDelete. Distinct names with no optional parameters, so no shipped signature changes (BinaryCompatibilityTests pins the old and the new).

Behavior

  • When the tool resolved for the source is DiffEngineViewer and that copy draws documents, a derived file opens no tool, costs nothing against MaxInstancesToLaunch, and is tracked with its source.
  • In every other case (the source is in Word or Beyond Compare, or in no tool) each file is launched exactly as before. Other diff tools are unaffected.
  • In the viewer the document's row reads + Sample.Test (pdf) (5). Accept move +5 and Discard +5 take the document and everything beneath it, the document last. Expand in the row's menu, or a click on the row once it is selected, gives each derived file a row of its own.
  • A page the document no longer has is a pending delete beneath it, carried out when the document is accepted.

Wire

Additive on all three, so an older tray, viewer or library yields ordinary rows and never a lost file:

  • viewer port request: a source: line on move, diff and delete
  • viewer port listing: a derived: key|source key line of its own, as held: is
  • tray port: an optional trailing "Source" on the Move and Delete payloads, which are byte for byte what they were without it

The tray stores and relays the marker; its menu is unchanged. The fold and the combined accept are the viewer's.

Notes

  • PiperTest.DeleteJson snapshotted a Move payload, so the "Add pending delete" sample in docs/tray.md showed a Move. It now shows a Delete.
  • DocumentWatch.Reread dropped Written when it re-read a held delete. It is carried now.
  • docs/diff-tool.md and diffTools.include.md pick up the 20.7.0-beta.1 version string. That is the test suite regenerating them, unrelated to this change.
  • The version is not bumped here.
  • Not run: the fold has been checked through the model, the ASCII screen and both wires, not in a window. Neither native head was run with one, and there is no pixel capture of a folded document. todo.md lists what is open.

The consumer is Verify 34, which reports the targets a converter derived from a document this way.

A snapshot library that splits a document into files (a png and the text of
each page, a csv per sheet) can say so: DiffRunner.LaunchDerived and
AddDerivedDelete name the received file of the pending source a file was
derived from.

When the viewer is drawing that source as a document, the derived files open
no tool, cost nothing against MaxInstancesToLaunch, and are shown beneath the
document's row, which accepts or discards them with it. In every other case
each file is launched exactly as before, so other diff tools are unaffected.

The marker is additive on all three wires: a source line on move, diff and
delete requests, a derived line on listings, and an optional Source property
on the tray's Move and Delete payloads. An older tray, viewer or library
yields ordinary rows, never a lost file.
@SimonCropp SimonCropp added this to the 20.7.0 milestone Oct 4, 2026
@SimonCropp
SimonCropp merged commit 7201664 into main Oct 4, 2026
11 checks passed
@SimonCropp
SimonCropp deleted the paged-documents branch October 4, 2026 11:44
This was referenced Oct 5, 2026
This was referenced Oct 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant