Expand darktable User Manual coverage of "custom sort"

[wbclay]

Please include a link to the Pull Request that you are documenting

#723

Tell us a little bit about this pull request

These mods are intended to fully resolve dtdocs issue #672. They contain a
comprehensive description of darktable's "custom sort" sequencing feature.
They reflect trial-and-error testing on DT v.5.0.0 and study of its database.
They should be reviewed by those knowledgeable of the relevant DT internals.

Custom sort may not not be DT's hottest feature, but it's an elegant mechanism
that deserves to be presented clearly. Many users are likely to find custom
sort very useful if they understand how to use it and are aware of a few
pitfalls (probably fixable in the future).

This pull request comprises mostly minor and easy-to-merge edits of 12 current
.md files as well as 2 new .md files.

Comprehensive change list by section number:

1.1.3, ./overview/user-interface/filmstrip.md
existing ¶ 2, append sentence w/link re. "custom sort" drag-and-drop

1.1.4, ./overview/user-interface/top-panel.md
existing filter/sort item, split items, edit each, link to fundamental concepts

1.3.1, ./overview/sidecar-files/sidecar.md
existing 1st sentence, insert footnote [^1] reference
add new footnote [^1], "custom sort" not saved in sidecar files (and why)

1.4.4, ./overview/workflow/export.md
existing list, insert new item 3, use of $(SEQUENCE) w/"image sequence" link

2.1, ./lighttable/overview.md
existing intro to "# keyboard shortcuts", consistency edit for additional item
add new item "drag and drop" w/two subordinate items

2.3, ./lighttable/undo-redo.md
existing 1st sentence, insert footnote [^2] reference
add new footnote [^2], no "Undo" for drag-and-drop "custom sort" order changes

2.4.1, ./lighttable/lighttable-modes/filemanager.md
existing item "select", clarity edit
add new items "hover" and "drag"

2.4.2, ./lighttable/lighttable-modes/zoomable-lighttable.md
existing item "select", clarity edit
add new item "hover"

2.5.5, ./lighttable/digital-asset-management/metadata-tagging.md
existing sentence after "# tagging," insert link, topic "image sequence"

2.5.6 (new), ./lighttable/digital-asset-management/sequence.md
add file, weight 70: new topic "image sequence"

2.5.7 (new), ./lighttable/digital-asset-management/custom-sort.md
add file, weight 80: new topic "custom sort"

8.3.5.3, ./module-reference/utility-modules/shared/export.md
existing item "filename template", insert sentence, $(SEQUENCE) example use

8.3.5.4, ./module-reference/utility-modules/shared/filmstrip.md
existing ¶ 3: replace last sentence, redundant with ¶ 4, 2nd sentence; add new last sentence re. "custom sort" w/link
existing ¶ 4, 2nd sentence: "different" image for k/b shortcuts; clarity edit

8.3.5.11, ./module-reference/utility-modules/shared/tagging.md
existing item "tag", append new sentence w/link re. "custom sort"

[0ion9]

Very interesting and well explained.

Be careful: an erroneous drag-and-drop can easily ruin one or more painstakingly-created image sequences.

Spurious drag and drop is almost unavoidable on graphics tablets -- attempting to 'click' on something often registers as a drag. Do you happen to know if this scenario (which typically would come through to dt as 'dropping the image on itself') is harmless WRT sequencing?

3. Long-distance drags are difficult because neither filemanager nor filmstrip scroll while you drag.
   [...]

This seems to me like a strong argument for making some kind of 'copy/paste' style resequencing available. Certainly it seems that on a longer ordering, with the current behaviours, you might have to plan your drags extensively, manually edit the DT database, or even apply tags to images in a particular order, to get just what you want.

A duplicated image inherits all of its origanal's tags

s/origanal's/original's/

resequencing behavior of collections based on multiple tags or on a mix of tagged and untagged images is not clear.

In this case I suspect that it is necessarily confusing, as you will have 'duplicate' indices arising. IMO drags should not perform reordering in the 'mixed tagged-ordering/global-ordering' scenario at all. And arguably in some other cases (all cases where there is not one clear recipient of the reordering operation; for example, surely reordering the collection TAGGED foo AND NOT TAGGED bar should affect the tag-based ordering of foo, whereas reordering the collection TAGGED foo OR TAGGED bar has no obvious correct recipient.)

A change request laments that editing tags regenerates the related "tagged image" database table in an unspecified order

Ideally, link the change request in question. But this is a minor point.

[wbclay]

Very interesting and well explained.

Thank you.

Unfortunately, it is significantly marred by a misconception I just found. The mistake: "collections based on multiple tags or on a mix of tagged and untagged images" do not exist. I mis-remembered that "collections", like "collection filters," could be comprised of multiple selection criteria. They cannot. A collection is defined by exactly one single-valued attribute, albeit possibly with subordinate values, like a date range or a folder with subfolders. I will remove or revise related text.

Spurious drag and drop is almost unavoidable on graphics tablets -- attempting to 'click' on something often registers as a drag. Do you happen to know if this scenario (which typically would come through to dt as 'dropping the image on itself') is harmless WRT sequencing?

Thanks for the heads-up. I don't have a tablet, so I haven't seen this issue. I remember tests confirming that dropping on the source image is harmless, but I will test that more thoroughly and post my findings when I next push revisions.

3. Long-distance drags are difficult because neither filemanager nor filmstrip scroll while you drag.
   [...]

This seems to me like a strong argument for making some kind of 'copy/paste' style resequencing available.

Agreed. It would avoid exactly the problems you describe in the succeeding paragraph (omitted here). Unfortunately, I don't have substantial graphics programming experience, so doubt I could tackle such a change.

s/origanal's/original's/

Thanks. If that's the only typo that slipped through, I did better than usual!

A change request laments that editing tags regenerates the related "tagged image" database table in an unspecified order

Ideally, link the change request in question. But this is a minor point.

Yeah, but it was lazy of me to leave it that fuzzy. I distinctly remember seeing such an issue, but have not been able to find it again. I'll look again, test it myself in any case and revise accordingly.

A question, if I may: I have used boldface where I thought it important, but I haven't noticed it elsewhere in the User Manual and haven't seen it mentioned in the dtdocs style guidelines. Is my use in this material acceptable?

I expect by Monday, Feb. 3, to push a 3rd commit to pull request's repository for the issues you've identified as well as a few minor improvements in wording.

Thanks again for the quick and careful review. Back soon with updates.

[github-actions]

This pull request has not had any activity in the past 60 days and will be closed in 365 days if not updated. Please verify it has no conflicts with the master branch and rebase if needed. Please add a comment if you need help or give permission to other people to finish your work.

[wbclay]

These comments respond to the 60-day inactivity notice issued 04 April 2025:

This pull request still has no conflicts with the base branch. However, it comprises additions and edits to about a dozen sections of the DT User Manual, and thus the longer it waits, the more likely that conflicts.

These changes are based on extensive practical testing with DT 5.0.1, examination of its database schema, and limited review of relevant sections of "collections" code. I am confident the text is are substantially correct and would appreciate review by knowledgeable developers followed by integration into the base along with whatever other updates are needed for DT v.5.

Please note also the related darktable issue 18584, a minor and probably easily fixed bug revealed by the testing for these documentation updates.

Many thanks to the DT developers and documentors for the impressive results of your efforts.

[paperdigits]

Don't worry, we are just moving a little slow. Since this a lot of information, it might take a little bit.

…

On April 3, 2025 10:34:32 PM PDT, Bill Clay ***@***.***> wrote: wbclay left a comment (darktable-org/dtdocs#723) These comments respond to the 60-day inactivity notice issued 04 April 2025: This pull request still has no conflicts with the base branch. However, it comprises additions and edits to about a dozen sections of the DT User Manual, and thus the longer it waits, the more likely that conflicts. These changes are based on extensive practical testing with DT 5.0.1, examination of its database schema, and limited review of relevant sections of "collections" code. I am confident the text is are substantially correct and would appreciate review by knowledgeable developers followed by integration into the base along with whatever other updates are needed for DT v.5. Please note also the related darktable issue 18584, a minor and probably easily fixed bug revealed by the testing for these documentation updates. Many thanks to the DT developers and documentors for the impressive results of your efforts. -- Reply to this email directly or view it on GitHub: #723 (comment) You are receiving this because you are subscribed to this thread. Message ID: ***@***.***>

[github-actions]

This pull request has not had any activity in the past 60 days and will be closed in 365 days if not updated. Please verify it has no conflicts with the master branch and rebase if needed. Please add a comment if you need help or give permission to other people to finish your work.