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.