From 1abb18d972c83ac81d722d3835f6aca81558dfdb Mon Sep 17 00:00:00 2001 From: Duncan Tourolle Date: Sat, 26 Sep 2026 13:22:15 -0400 Subject: [PATCH] Specify albums and pointing at folders, and describe them in the manual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FR-EXP-10 is the album: a named export destination beneath the collections, whose folder holds only the exported files while the catalog links each back to its original; how albums sync, why a device folder does not, and why the tables are made on first use rather than by a migration. FR-EXP-6 now says the destination is an album, never inside the library, and that folders are chosen by pointing — the portal or Windows dialogue, SAF's tree picker, the server browser — each able to make a folder. The manual's launch and export sections say the same in the words on screen. Its pictures still show the 0.16.0 launch screen and export settings; they are re-recorded with the rig, not edited by hand. --- docs/dev/requirements.md | 26 ++++++++++++++++++++++++-- docs/manual/README.md | 27 +++++++++++++++++++++++---- docs/manual/index.html | 24 ++++++++++++++++++++---- 3 files changed, 67 insertions(+), 10 deletions(-) diff --git a/docs/dev/requirements.md b/docs/dev/requirements.md index 15ab30b..98cde24 100644 --- a/docs/dev/requirements.md +++ b/docs/dev/requirements.md @@ -867,8 +867,16 @@ full-size TIFF alongside a 2048px sRGB JPEG. **FR-EXP-6 — Naming and destination.** Output filenames are generated from a template supporting at minimum: original filename, sequence number, capture date, export dimensions, and preset name. -Collision policy (overwrite / skip / auto-increment) is configurable. Destinations include a local -path and a Nextcloud remote path (FR-NC-7). +Collision policy (overwrite / skip / auto-increment) is configurable. The destination is an album +(FR-EXP-10), whose folder is on this device or on the library's server (FR-NC-7) — never inside the +library itself, where a scan would catalogue the exported files as photographs. + +A folder is chosen by pointing, never by typing a path: the platform's own dialogue on the desktop +(the XDG desktop portal on Linux, which reaches the user's files from inside the Flatpak; the common +item dialogue on Windows), the Storage Access Framework's tree picker on Android, and an in-app +browser for a folder on the server. Every one of them can make a new folder as well as open one. +The same applies to the other folders the application asks for on the desktop — the library folder, +an import's source and second copy, and presets brought across from Lightroom. **FR-EXP-7 — Batch export.** Export a selection with one or more presets, running in the background with progress and cancellation. Uses all available cores and the GPU. A failure on one image is @@ -881,6 +889,20 @@ strip GPS and personal metadata. Copyright and contact fields are settable per-p regardless of what the display was showing — including the high-quality demosaic (FR-RAW-3), never the fast preview method. +**FR-EXP-10 — Albums.** An album is a named export destination listed in the library sidebar +beneath the collections. Its folder holds only the exported files; the catalog records, for each +file written there, the image it was rendered from, so that selecting the album shows the originals +behind its files and re-exporting after an edit is one selection away. The export sheet chooses an +album by name, and an export with no album chosen is refused and says so. + +Albums sync between devices as collections do (FR-CAT-7): by uuid and revision, deletions as +tombstones, exports as a set union keyed on the server's file id. A folder on the server syncs with +the album; a folder on the device does not, because a path or a SAF grant on one device means +nothing on another — an album made elsewhere arrives with no folder here until one is chosen. +Deleting an album never deletes the files in its folder. The album tables are created on first use +rather than by a schema migration, so a device on an older build keeps merging the rest of the +catalog. + ### 3.7 Nextcloud integration Mechanics below are verified against Nextcloud 34 documentation and server/desktop-client source. diff --git a/docs/manual/README.md b/docs/manual/README.md index 5a33047..aefea19 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -15,7 +15,10 @@ The photographs are the author's. None show a person. DarkRoom opens on a library: a folder on this machine, a folder a sync client keeps, or a Nextcloud account. A folder needs no password and uploads -nothing. +nothing. `Choose folder…` opens your desktop's own folder dialogue, which can +make a new folder too; the folder used last stays on the screen with +`Open folder` beside it. On a Nextcloud account the library folder is chosen +in a browser of the server, whose `New folder` makes one there. ![The launch screen: a server field, a folder field, and which formats to scan for](media/launch.png) @@ -300,9 +303,25 @@ as the first step in its history. ## Export `Export` in the develop header, or `Export N` from a selection. Format, -size, colour space, sharpening, naming and where the file goes are in -Settings, and apply to every export until changed. An export with no folder -set is refused, and the header says so. +size, colour space, sharpening and naming are in Settings, and apply to every +export until changed. Where the file goes is an album. + +An album is a folder exports go to, listed under **Albums** in the sidebar, +below the collections. Press `+` there, or `New album…` in the export sheet +(`Ctrl+E`), name it, and choose its folder: on this device, in the system's +folder dialogue (on the tablet, Android's folder picker), or on the server, +in a browser that can make a folder as well as open one. Not inside the +library — a JPEG exported there would come back from the next scan as a +photograph of its own, and the browser says so rather than letting you. + +The folder holds only the exported files. The album remembers which +photograph each came from, so selecting it in the sidebar shows the +originals behind its JPEGs — edit one and export it again. Albums reach your +other devices as collections do; a folder on this device does not, so an +album made on the desktop asks the tablet for a folder of its own. Deleting +an album leaves its files where they are. + +An export with no album chosen is refused, and the header says so. ![Export defaults in Settings](media/settings-export.png) diff --git a/docs/manual/index.html b/docs/manual/index.html index e7578e6..6c19ded 100644 --- a/docs/manual/index.html +++ b/docs/manual/index.html @@ -148,7 +148,10 @@ is only about what you see.

Opening a library

DarkRoom opens on a library: a folder on this machine, a folder a sync client keeps, or a Nextcloud account. A folder needs no password and uploads -nothing.

+nothing. Choose folder… opens your desktop's own folder dialogue, which can +make a new folder too; the folder used last stays on the screen with +Open folder beside it. On a Nextcloud account the library folder is chosen +in a browser of the server, whose New folder makes one there.

The launch screen: a server field, a folder field, and which formats to scan for
The launch screen: a server field, a folder field, and which formats to scan for

Once a folder is named, it is the library — you are not asked for it again, and Open library opens it whole. Subfolder… narrows the scan to part of @@ -347,9 +350,22 @@ as the first step in its history.

The same, with the ragged border filled by the model rather than cropped away
The same, with the ragged border filled by the model rather than cropped away

Export

Export in the develop header, or Export N from a selection. Format, -size, colour space, sharpening, naming and where the file goes are in -Settings, and apply to every export until changed. An export with no folder -set is refused, and the header says so.

+size, colour space, sharpening and naming are in Settings, and apply to every +export until changed. Where the file goes is an album.

+

An album is a folder exports go to, listed under Albums in the sidebar, +below the collections. Press + there, or New album… in the export sheet +(Ctrl+E), name it, and choose its folder: on this device, in the system's +folder dialogue (on the tablet, Android's folder picker), or on the server, +in a browser that can make a folder as well as open one. Not inside the +library — a JPEG exported there would come back from the next scan as a +photograph of its own, and the browser says so rather than letting you.

+

The folder holds only the exported files. The album remembers which +photograph each came from, so selecting it in the sidebar shows the +originals behind its JPEGs — edit one and export it again. Albums reach your +other devices as collections do; a folder on this device does not, so an +album made on the desktop asks the tablet for a folder of its own. Deleting +an album leaves its files where they are.

+

An export with no album chosen is refused, and the header says so.

Export defaults in Settings
Export defaults in Settings

Settings

The settings page: background activity, indexing, storage, display
The settings page: background activity, indexing, storage, display