Expand darktable User Manual coverage of "custom sort"

content/lighttable/digital-asset-management/collections.md

@@ -6,10 +6,12 @@ weight: 20
 author: "people"
 ---
 
-A collection is a set of images matching a given selection criteria. 
+A collection is a set of images matching a given selection criterion. 
 
 The most basic kind of collection is a film roll, which contains all of the images that have been imported from a specific folder on disk. Whenever you [import](../../module-reference/utility-modules/lighttable/import.md) images from the filesystem, those images are organized in a film roll whose name is derived from that of their parent folder. 
 
-You can easily construct other kinds of collection based on various image attributes (Exif data, filename, tags etc.) in the [collections](../../module-reference/utility-modules/shared/collections.md) module. Multiple criteria can be logically combined to narrow or extend your collection.
+You can easily construct other kinds of collection based on one of many image attributes (Exif data, filename, tags, etc.) in the [collections](../../module-reference/utility-modules/shared/collections.md) module.[^1] The [collection filters](../../module-reference/utility-modules/shared/collection-filters.md) module sets selection and exclusion criteria for many attributes to refine the focus of darktable's display, processing, and export of a collection.
 
 darktable retains a list of the most recently used collections for quick access. These can be accessed from the [recent collections](../../module-reference/utility-modules/shared/recent-collections.md) module.
+
+[^1]: While collections are based on a single attribute, the attribute's selection criterion may be multi-valued (_i.e._, range, wild-card expression, or non-leaf hierarchy node).

content/lighttable/digital-asset-management/custom-sort.md

@@ -0,0 +1,72 @@
+---
+title: custom sort
+id: custom-sort
+weight: 80
+author: "wbclay"
+---
+
+Setting _sort by_ > "custom sort" presents images in any sequence you define. Images are initally ordered by an image property (import order, image capture time, file name, etc.) but you can then incrementally alter "custom sort" sequences by drag-and-drop. Be careful: an erroneous drag-and-drop can easily ruin one or more painstakingly-created image sequences.
+
+### cautions {#cautions}
+
+- "Undo" __does not reverse__ drag-and-drop resequencing.
+
+- Drag-and-drop resequencing is __always__ enabled in lighttable filemanager and in the filmstrip, but any resulting __changes are invisible__ if _sort by_ > "custom sort" is not in effect.
+
+- Do not use "custom sort" for tag-based collections that specify a wild-card ("*" or "%") expression.[^1]
+
+[^1]: When a wild-card tag expression does not resolve to a __single__ tag, then drag-and-drop operates on only the first matching tag's sequence. If that tag is attached to a source image, the image is resequenced. If the same tag is also attached to the target image, the drop occurs there; if not, resequenced images appear at the collection's "custom sort" tail or head. If the first matching tag is not attached to a source image, the image is not repositioned. Collections preference "tag case sensitivity" is relevant beyond case: "insensitive" treats "%" (but not "*") as a string-match wild card. The global sequence is not affected in any of these cases.
+
+- Ensure any image you drag is __not selected__ unless you want to reposition the entire currently selected set.
+
+- Aim your "drops" accurately: verify the correct target is __highlighted__ before dropping!
+
+- "custom sort" positions are lost if images are removed from darktable or their tags are detached or deleted ([why?](../../../overview/sidecar-files/sidecar.md/#fn:1)). 
+
+### _which_ custom sort sequence?
+
+Collection type determines which [image sequence](../../lighttable/digital-asset-management/sequence.md) drag-and-drop changes. If the collection's selection criterion is _tag_, a __tag-based__ "custom sort" sequence is altered. Otherwise, the __global__ "custom sort" sequence is altered. Collection filters (even if tag-based) do not influence which sequence drag-and-drop changes.
+
+When _sort by_ > "custom sort" is in effect, dragged-and-dropped images are immediately presented in their new tag-based or global "custom sort" sequence.
+
+### what to drag, where to drop?
+
+While viewing a collection in filemanager or the filmstrip, you may drag any hovered-over (highlighted) image to any other image in the displayed collection. Empty space before, between, or after images is not a recognized drop target.
+
+You may relocate a single image (unselected or sole selection) or a selected set of images by dragging one of them to the desired position as follows:
+
+- Drop on the image you want a dragged image or selected set to __precede__ when _sort order_  is __"ascending"__.
+
+- Drop on the image you want a dragged image or selected set to __follow__ when _sort order_  is __"descending"__.
+
+- Abort an accidental drag by dropping the dragged image _outside_ of the thumbnail display. If all peripheral panels are hidden, then drop the dragged image on __itself__. If multiple images were selected, the entire selected set will be relocated to that spot.
+
+- If the "dropped on" image is subsequently resequenced, filtered out, or even deleted, the dropped image(s) remain where the "dropped on" image was located.
+
+### who's last? (or, in descending sort, first?)
+
+- An image dropped after the last image on lighttable is regarded as dropped __on the last image__, thus positioned before it. 
+
+- To change the last image in an "ascending" "custom sort" display, drop it on the existing last image, then drag-and-drop that last image on its intended replacement. 
+
+- If you expect to use a "descending" sort, do the opposite to change the first image.
+
+### suggested process
+
+1. If you intend to present a collection in more than one "custom sort" sequence or if some images in a collection are included in other collections to be displayed with a different global "custom sort", then tag-based collections should be used.
+
+2. For tag-based "custom sort" only: 
+- Set _sort by_ to the image attribute and _sort order_ (ascending or descending) you want as your tag's initial sequence, 
+- Select the images to be sequenced, and
+- in the right-hand panel at _tagging_, bottom half, add a new tag or click on an existing tag.
+- The tag is now attached to the selected images in the displayed sequence. Note the tag's increased image count.
+- Change _collections_ selection crierion to "tag" and choose the newly-applied tag. Note that the newly-tagged images are shown.
+
+3. Long-distance drags are difficult because neither _filemanager_ nor _filmstrip_ scroll while you drag. Try to fit drag sources and targets onto the same screen by maximizing the the window and scrolling the display. If that's not sufficient: 
+- increase the number of images displayed (thus shrinking thumbnails) or
+- hide images between drag source and drop target using _collection filters_ (e.g., by ranges of "datetime captured" or "image id").
+
+4. Rearrange the images as you desire:
+- __Clear any active selection__: _selection_ > _select none_.
+- Set _sort by_ > "custom sort" so you can verify your changes immediately.
+- Remember the __[cautions](#cautions)__ above as you drag-and-drop.

content/lighttable/digital-asset-management/metadata-tagging.md

@@ -14,4 +14,4 @@ Metadata (e.g. title, description) is free-format text that usually differs for
 
 # tagging
 
-Tags are usually shared between multiple images and are used to categorise and group them. You can add tags to images in the [tagging](../../module-reference/utility-modules/shared/tagging.md) module.
+Tags are usually shared between multiple images and are used to categorise, group, and/or [sequence](../../lighttable/digital-asset-management/sequence.md) them. You can add tags to images in the [tagging](../../module-reference/utility-modules/shared/tagging.md) module.

content/lighttable/digital-asset-management/sequence.md

@@ -0,0 +1,26 @@
+---
+title: image seqence
+id: sequence
+weight: 70
+author: "wbclay"
+---
+
+A collection's images are always presented in a specific _sort by_ sequence that determines the order of their display, processing, and export, which it is often convenient to control  (_e.g._, for a slideshow or document).
+
+You may choose an [image attribute](../../module-reference/utility-modules/shared/collections/#filtering-attributes) (filename, capture time, rating, title, etc.) as the sort criterion in the _sort by_ pull-down menu and icon at the left-hand-side of darktable's [top panel](../../../overview/user-interface/top-panel/) or combine multiple sort criteria by clicking on _new sort_ in the left panel at the bottom of the  [collection filters](../../module-reference/utility-modules/shared/collection-filters/#sorting).
+
+Whatever _sort by_ criterion is chosen, a collection may contain some images you need to present in a different order. In such cases, darktable's [custom sort](../../lighttable/digital-asset-management/custom-sort.md) allows you to alter image sequence directly by dragging and dropping thumbnails in lighttable filemangager or the filmstrip.
+
+There are two distinct "custom sort" sequencing regimes:
+
+- One __global sequence__ over every image in a darktable repository.
+
+- Multiple __tag-based__ sequences, one for each tag associated with one or more images.
+
+When an image is imported into your darktable library, it is automatically positioned in the global sequence after all previously-imported images. A duplicated image is initially positioned in the global sequence immediately after its original, regardless of intervening image imports.
+
+Tagged images are sequenced within each attached tag in the order that the tag is attached. Selected sets of images are tagged in order of the _sort by_ setting in effect at the moment the tag is attached. Newly-tagged images are initially positioned after all images previously associated with that tag. A duplicated image inherits all of its original's tags and is positioned within each as a newly-tagged image.
+
+A collection's __selection criterion__ determines which sequence drag-and-drop alters while working in lighttable filemanager or the filmstrip. Drag-and-drop withn a tag-based collection alters a designated tag's sequence. Otherwise, drag-and-drop alters the global sequence of all images in the library.
+
+The next section, [custom sort](../../lighttable/digital-asset-management/custom-sort.md), suggests how to efficiently and safely use drag-and-drop image resequencing. __Note its [cautions](./custom-sort.md#cautions).__

content/lighttable/lighttable-modes/filemanager.md

@@ -17,4 +17,10 @@ navigate
 : You can navigate through the images using the arrow keys (←/→/↑/↓) or by scrolling with your mouse. Press the Home key to scroll to the top of the collection, the End key to scroll to the bottom, and PageUp/PageDown to scroll up/down by a page.
 
 select
-: You can select the image under the pointer by clicking on its thumbnail or by pressing Enter. A range of images can be selected by clicking on the first image and then Shift+clicking on the last one. Images can be added or removed from a selection by Ctrl+clicking on their thumbnails or by pressing Spacebar.
+: You can select the image under the pointer by clicking on its thumbnail or by pressing Enter. To select a range of images, click on the first image and then Shift+click on the last one. To add or remove images in a selection, Ctrl+click on a thumbnail or hover over a thumbnail and press Spacebar.
+
+hover
+: When the pointer hovers over any image's thumbnail, it is highlighted and its image implicitly selected for keyboard shortcuts. If that thumbnail is part of a currently-selected set, certain shortcuts will be applied to _all_ images of the set (for example, a numeric digit star rating). 
+
+drag
+: You can drag a thumbnail (__along with any selected set__ to which it may belong) to set its [custom sort](../../lighttable/digital-asset-management/custom-sort.md) position just before or after the image it's dropped upon.

content/lighttable/lighttable-modes/zoomable-lighttable.md

@@ -18,8 +18,10 @@ navigate
 : Hold down the left mouse button and drag to move the lighttable around and navigate through your collection.
 
 select
-: As with the filemanager mode, you can select the image under the pointer by clicking on its thumbnail or by pressing Enter. A range of images can be selected by clicking on the first image and then Shift+clicking on the last one. Images can be added to or removed from a selection by Ctrl+clicking on their thumbnails or by pressing Spacebar.
+: As with the filemanager mode, you can select the image under the pointer by clicking on its thumbnail or by pressing Enter. To select a range of images, click on the first image and then Shift+click on the last one. To add or remove images in a selection, Ctrl+click on a thumbnail or hover over a thumbnail and press Spacebar.
 
+hover
+: Hovering over a thumbnail highlights and impicitly selects it for keyboard shortcuts as in filemanager mode. However, dragging pans the entire thumbnail display, so you cannot change images' [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order in this mode.
 ---
 
 **Hint:** you may find that image thumbnails are slow to load when zooming quickly through a large collection. One way to speed up the navigation is to generate a cache containing all the thumbnails using the [`darktable-generate-cache`](../../special-topics/program-invocation/darktable-generate-cache.md) command.

content/lighttable/overview.md

@@ -10,7 +10,9 @@ The lighttable view allows you to view and manage your image collection.
 
 The centre view contains thumbnails of your images -- how they are displayed depends on which [mode](./lighttable-modes/_index.md) you are working in.
 
-While the mouse is over an image thumbnail or images are selected, there are a number of actions you can perform with keyboard shortcuts:
+While the mouse is over an image thumbnail or images are selected, there are a number of actions you can perform:
+
+# keyboard shortcuts
 
 - `F1, F2, F3, F4, F5` adds or removes a color label (red, yellow, green, blue, purple, respectively). A color label will be added if _any_ selected image does not currently have the label; otherwise the label will be removed
 
@@ -33,3 +35,9 @@ While the mouse is over an image thumbnail or images are selected, there are a n
 - `W ` fully zooms into the current image while the key is pressed
 
 - `Ctrl+W ` fully zooms into the current image and show areas in focus
+
+# drag-and-drop
+
+- You may change the sequence of images displayed, processed, or exported when _sort by_ is set to [custom sort](../../lighttable/digital-asset-management/custom-sort.md) by dragging and dropping their thumbnails.
+
+- Use of this feature requires careful attention. __Note its [cautions](./digital-asset-management/custom-sort.md#cautions).__

content/lighttable/undo-redo.md

@@ -6,6 +6,8 @@ weight: 30
 author: "people"
 ---
 
-Most changes made within the lighttable are recorded and can be reverted to a previous state. This includes modifications to color labels, ratings, geo-localization, tags, metadata, orientation, copy/paste of history, image duplication, or application of a style. Note that the facility to undo/redo actions is unlimited in the number of steps while in the lighttable view, but it is reset each time you switch to a different view.
+Most changes made within the lighttable are recorded and can be reverted to a previous state.[^1] This includes modifications to color labels, ratings, geo-localization, tags, metadata, orientation, copy/paste of history, image duplication, or application of a style. Note that the facility to undo/redo actions is unlimited in the number of steps while in the lighttable view, but it is reset each time you switch to a different view.
+
+[^1]: "Undo" __cannot reverse__ changes made in images' [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order by dragging-and-dropping thumbnails in lighttable filemanager and the filmstrip.
 
 Press Ctrl+Z to undo the last modification and Ctrl+Y to redo the last undone modification (if any).

content/module-reference/utility-modules/shared/export.md

@@ -20,7 +20,7 @@ target storage
 : The type of location to store your selected images. A number of different back-ends are implemented, including file on disk, LaTeX book template and various web albums. Depending on the selected target, you will be asked to provide additional information, such as filenames or account name and password.
 
 filename template
-: Define the folder and file to which the image will be exported. This can be automatically generated using several pre-defined variables. See the [variables](../../../special-topics/variables.md) section for details.
+: Define the folder and file to which the image will be exported. This can be automatically generated using several pre-defined variables. For example, `$(SEQUENCE)` in a template records sequence number of the image exported to the target. See the [variables](../../../special-topics/variables.md) section for details.
 
 output directory selector
 : The button beside the filename template entry opens a dialog to select the parent directory for export.

content/module-reference/utility-modules/shared/filmstrip.md

@@ -12,12 +12,14 @@ The filmstrip can be used to quickly switch between images. The images shown are
 
 The filmstrip can be switched on and off using the shortcut Ctrl+F. The height of the filmstrip panel can be changed by clicking and dragging its top border.
 
-Quickly navigate through the images in the filmstrip by scrolling with the mouse. Increase scroll speed with Shift+scroll. Change the height of the filmstrip with Ctrl+scroll or by clicking+dragging the top of the panel. In the darkroom you can change the photo currently being processed by clicking on another image in the filmstrip.
+Quickly navigate through the images in the filmstrip by scrolling with the mouse. Increase scroll speed with Shift+scroll. Change the height of the filmstrip with Ctrl+scroll or by clicking+dragging the top of the panel. Change the _custom sort_ order of images by dragging and dropping thumbnails as described at [custom sort](../../../../lighttable/digital-asset-management/custom-sort.md).
 
-In the darkroom, the image currently being processed is selected and highlighted. Click on or hover over an image on the filmstrip with your mouse to select it (in order to act on it with a keyboard shortcut) without changing the image being processed. Double-click on an image to open it for editing.
+In the darkroom, the image currently being processed is selected and highlighted. Click on or hover over a different image on the filmstrip with your mouse in order to act on it with a keyboard shortcut _without changing the image being processed_. Double-click on an image to open it for editing.
 
 If you wish to select multiple images in the filmstrip, click to select the first image followed by either Ctrl+click to select or de-select further images, or Shift+click to select a range of images.
 
+
+
 The following shortcuts can be used to select images in the filmstrip:
 
 - `Ctrl+A` selects all images in the filmstrip
@@ -26,6 +28,7 @@ The following shortcuts can be used to select images in the filmstrip:
 
 - `Ctrl+I` inverts the current selection
 
+
 The following shortcuts can be used to perform operations on the selected images
 
 - `F1, F2, F3, F4, F5` adds or removes a color label (red, yellow, green, blue, purple, respectively). A color label will be added if _any_ selected image does not currently have the label; otherwise the label will be removed

content/module-reference/utility-modules/shared/tagging.md

@@ -21,6 +21,8 @@ tag
 
 : You can assign properties (name, private, category, synonyms and image order) to a tag.
 
+: You can use tag names to define  [collections](../collections/) that are displayed, processed, and exported in a _durable_ [custom sort](../../../lighttable/digital-asset-management/custom-sort/) order, unchanging when other collections sharing some of the same images are reordered.
+
 node
 : Any path that forms part of a tag is a node. In the above example, "`places`", "`places|France`", "`places|France|Nord`" and "`places|France|Nord|Lille`" are all nodes. In the hierarchical tree view, the nodes form the branches and leaves of the tree.