proposed custom sort documentation and extensions

[wbclay]

The following (once reviewed and corrected by more knowledgeable users and/or developers) might be a useful section added to the Darktable user manual at darktable / Lighttable / digital asset management / custom sort:

"Custom sort" is scarcely documented but elegantly implemented. This explanation is based on trial and error and database schema examination of darktable 4.8.1. It may be incomplete, incorrect, and/or obsolete; corrections welcome.

While viewing a collection in lighttable, you may alter the image's position in the collection via drag-and-drop. A dragged image will later appear immediately BEFORE the image upon which it was dropped when "custom sort" is set in lighttable's "sort by" pull-down menu (if it's an ascending sort; descending, the dropped image appears immediately AFTER the image it was dropped on).

A given image's "custom sort" position may be set independently in any number of different tag-based collections (NOT filters) that include it. However, only a SINGLE position is set for for that image all other collections.

Caveats:

1. Drag-and-drop works with ANY "sort by" setting in lighttable, but the result is visible only when "custom sort" is set.
2. If you drag-and-drop on a non-tag-based collection's lighttable (possibly filtered) and one or more of the relocated images are included in another non-tag-based collection or in a different filter set that is subsequently resequenced, the prior location of each newly-relocated image is overwritten.
3. An image dropped AFTER the last image on lighttable is regarded as dropped ON the last image; to set a different last image, drop it on the existing last image, then drag-and-drop that last image on its new predecessor.
4. Relocating a "dropped-on" image does NOT relocate images that were dropped on it earlier; they remain where the "dropped on" image was previously located.
5. If filter changes obscure a "dropped on" image, a "dropped" image will still appear where it would if the "dropped on" image were displayed, filters permitting.
6. A change request laments that editing tags regenerates the related "tagged image" database table in default sequence (image id<<32?), losing its previous "custom sort."
7. Although tags ARE recorded in images' sidecar files, the related sequence numbers are NOT, nor is the non-tag-collection sequence number. Thus, "custom sorts" cannot be recovered from sidecar files after database deletions.

Suggested usage:

It's best to resequence a collection with NO filters active or at least with the least selective set of filters you expect to use. Otherwise, if you expand the filtered set, you will likely find your desired sequence confused.

If a collection will be displayed in more than one "custom sort" sequence or if some images in that collection also participate in other collections to be displayed in a different "custom sort," define and use tag-based collections.

Wish list (maybe someone [perhaps even I, a LUA relative newbie] will cobble together some LUA modules):

1. For tag-based collections, initialize an image's "custom sort" sequence to reflect its currently-displayed sort at the moment the image is tagged (so, for example, you can present images taken independently with multiple cameras generally in chronological order, but still easily tweak the sequence as taste and story-telling demand).
2. Add a "collections" setting "resequence" which resets the sequence attribute of the current collection's images to reflect their currently displayed sort (i.e., a one-time images table or tagged_images table update, not really a setting).
3. Record "custom sort" sequence numbers in sidecar files.
4. For non-tag-based collections, warn (with a "do not repeat" checkbox) on a drag-and-drop attempt for a previously resequenced image.

[paperdigits]

Hey thank you for the text. Can you possibly form this into a pull request?

This is also the wrong place for "wish list" items, those will need an issue opened in the main darktable repo

[github-actions]

This issue has not had any activity in the past 60 days and will be closed in 365 days if not updated.