update doc on keep-icloud-recent-days and links

.github/workflows/produce-artifacts.yml

@@ -24,7 +24,7 @@ jobs:
         with:
           concurrent_skipping: 'same_content_newer'
           skip_after_successful_duplicate: 'true'
-          paths_ignore: '["**/*.md", "examples/**", "tests/**"]'
+          paths_ignore: '["**/*.md", "examples/**", "tests/**", "docs/**"]'
           do_not_skip: '["workflow_dispatch", "schedule"]'
 
   get_version:

README.md

@@ -25,7 +25,7 @@ See [Documentation](https://icloud-photos-downloader.github.io/icloud_photos_dow
 - Three modes of operation:
   - **Copy** - download new photos from iCloud (default mode)
   - **Sync** - download new photos from iCloud and delete local files that were removed in iCloud (`--auto-delete` option)
-  - **Move** - download new photos from iCloud and delete photos in iCloud (`--delete-after-download` option)
+  - **Move** - download new photos from iCloud and delete photos in iCloud (`--keep-icloud-recent-days` option)
 - Support for Live Photos (image and video as separate files) and RAW images (including RAW+JPEG)
 - Automatic de-duplication of photos with the same name
 - One time download and an option to monitor for iCloud changes continuously (`--watch-with-interval` option)

docs/authentication.md

@@ -21,14 +21,14 @@ There are two ways to provide MFA code to `icloudpd`:
 - Using console
 - Using web interface
 
-The choice can be made with `--mfa-provider` parameter.
+The choice can be made with [`--mfa-provider`](mfa-provider-parameter) parameter.
 
 Default: *console*
 Other options: *webui*
 
 ## Access from Mainland China
 
-Access to iCloud.com is blocked from mainland China. `icloudpd` can be used with `--domain cn` parameter to support downloading iCloud Photos from mainland China, however, people reported mixed results with that parameter.
+Access to iCloud.com is blocked from mainland China. `icloudpd` can be used with [`--domain cn`](domain-parameter) parameter to support downloading iCloud Photos from mainland China, however, people reported mixed results with that parameter.
 
 ## FIDO
 
@@ -51,12 +51,12 @@ WebUI support
 ```
 
 Passwords for iCloud access can be supplied by user in four ways:
-- Using `--password` command line parameter
+- Using [`--password`](password-parameter) command line parameter
 - Using keyring
 - Using console
 - Using web interface
 
-It is possible to specify which of these three ways `icloudpd` should use, by specifying them with `--password-provider` parameter. More than one can be specified and the order
+It is possible to specify which of these three ways `icloudpd` should use, by specifying them with [`--password-provider`](password-provider-parameter) parameter. More than one can be specified and the order
 of providers matches the order then will be checked for password. E.g. `--password-provider keyring --password-provider console` means that `icloudpd` will check password in keyring first and then, if no password found, ask for password in the console.
 
 Keyring password provider, if specified, saves valid password back into keyring.

docs/install.md

@@ -17,7 +17,7 @@ There are three ways to run `icloudpd`:
 docker run -it --rm --name icloudpd -v $(pwd)/Photos:/data -e TZ=America/Los_Angeles icloudpd/icloudpd:latest icloudpd --directory /data --username [email protected] --watch-with-interval 3600
 ```
 
-Image asset date will be converted to specified TZ and then used for creating folders ([see `--folder-structure` parameter](#folder_structure))
+Image asset date will be converted to specified TZ and then used for creating folders (see [`--folder-structure`](folder-structure-parameter) parameter)
 
 Synchronization logic can be adjusted with command-line parameters. Run the following to get full list:
 ``` sh 

docs/mode.md

@@ -14,13 +14,9 @@ Copy
 Sync
 :   Download assets from iCloud that are are not in the local storage (same as Copy). In addition, delete local files that were removed in iCloud (moved into "Recently Deleted" album)
 
-    This mode is selected with `--auto-delete` parameter
+    This mode is selected with [`--auto-delete`](auto-delete-parameter) parameter
 
 Move
-:   Download assets from iCloud that are are not in the local storage (same as Copy). Then delete assets in iCloud that were just downloaded 
+:   Download assets from iCloud that are are not in the local storage (same as Copy). Then delete assets in iCloud that are in local storage, optionally leaving recent ones in iCloud
 
-    This mode is selected with `--delete-after-download` parameter
-
-    ```{note}
-    If remote assets were not downloaded, e.g. because they were already in local storage, they will NOT be deleted in iCloud.
-    ```
+    This mode is selected with [`--keep-icloud-recent-days`](keep-icloud-recent-days-parameter) parameter

docs/naming.md

@@ -12,13 +12,13 @@ Support for `none` value added
 Support for OS locale added
 ```
 
-`icloudpd` uses asset metadata (_created date_) to build folder hierarchy, and it can be adjusted with `--folder-structure` parameter.
+`icloudpd` uses asset metadata (_created date_) to build folder hierarchy, and it can be adjusted with [`--folder-structure`](folder-structure-parameter) parameter.
 
 Specifying `--folder-structure none` will put all files into one folder.
 
 ### Formatting
 
-`icloudpd` follows [Python string formatting grammar](https://docs.python.org/3/library/string.html#formatstrings) for `--folder-structure` parameter,e.g. `{:%Y}` means the need to take only 4-digit year out of created date. Full list of format codes is [available](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes).
+`icloudpd` follows [Python string formatting grammar](https://docs.python.org/3/library/string.html#formatstrings) for [`--folder-structure`](folder-structure-parameter) parameter,e.g. `{:%Y}` means the need to take only 4-digit year out of created date. Full list of format codes is [available](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes).
 
 Default format is: `{:%Y/%m/%d}`
 
@@ -27,7 +27,7 @@ Default format is: `{:%Y/%m/%d}`
 ```{versionadded} 1.22.0
 ```
 
-Some formatting codes, e.g. `%B` for printing full month, are specific to the language. By default `icloudpd` uses English regardless of the locale of the OS. With `--use-os-locale` the behavior can be changed.
+Some formatting codes, e.g. `%B` for printing full month, are specific to the language. By default `icloudpd` uses English regardless of the locale of the OS. With [`--use-os-locale`](use-os-locale-parameter) the behavior can be changed.
 
 Example of running `icloudpd` with  specific locale under Linux or MacOS:
 
@@ -41,7 +41,7 @@ LC_ALL=ru_RU.UTF.8 icloudpd --use-os-locale --version
 `--file-match-policy` parameter added and `name-id7` policy implemented
 ```
 
-In large iCloud collections it is possible to have name collisions. To avoid collisions if files need to be downloaded into the same folder, use `--file-match-policy` parameter:
+In large iCloud collections it is possible to have name collisions. To avoid collisions if files need to be downloaded into the same folder, use [`--file-match-policy`](file-match-policy-parameter) parameter:
 - add unique invariant asset identification suffix to the name (e.g. **"IMG_1234_QAZXSW.JPG"**) with `--file-match-policy name-id7`
 - de-duplicate by adding file size as a suffix (e.g. **"IMG_1234-67890.JPG"** for second asset); `--file-match-policy name-size-dedup-with-suffix` - it is default
 
@@ -51,7 +51,7 @@ In large iCloud collections it is possible to have name collisions. To avoid col
 `--live-photo-mov-filename-policy` parameter added and `original` policy implemented
 ```
 
-Live Photo assets have two components: still image and short video. `icloudpd` can download both and allows customizing file name of the video portion with `--live-photo-mov-filename-policy` parameter:
+Live Photo assets have two components: still image and short video. `icloudpd` can download both and allows customizing file name of the video portion with [`--live-photo-mov-filename-policy`](live-photo-mov-filename-policy-parameter) parameter:
 
 - Use video file name the same as still image with `original` policy; use `--file-match-policy name-id7` to avoid clashes of video file with other videos.
 - Use suffix from the still image with `suffix` policy: **"IMG_1234_HEVC.MOV"** for **"IMG_1234.HEIC"** still. This is default and works for HEIC still images only
@@ -62,4 +62,4 @@ Live Photo assets have two components: still image and short video. `icloudpd` c
 `--keep-unicode-in-filenames` parameter flag added with default `false` 
 ```
 
-Unicode characters are stripped from file names for better compatibility. `icloudpd` can leave them when `--keep-unicode-in-filenames` is specified.
+Unicode characters are stripped from file names for better compatibility. `icloudpd` can leave them when [`--keep-unicode-in-filenames`](keep-unicode-in-filenames-parameter) is specified.

docs/raw.md

@@ -34,7 +34,7 @@ One representation will be `original` [size](size) and another `alternative`.
 As of June 2024, icloud.com always shows assets with two representations as RAW+JPEG. Photo app on Mac
 allows choosing which representation to treat as original, but it is not clear what that setting changes. 
 
-`icloudpd` disambiguates the behavior with `--align-raw` parameter:
+`icloudpd` disambiguates the behavior with [`--align-raw`](align-raw-parameter) parameter:
 
 - *original* always treat RAW as original [size](size)
 - *alternative* always treat RAW as alternative [size](size)

docs/reference.md

@@ -182,16 +182,32 @@ This is a list of all options available for command line interface (CLI) of the
 (delete-after-download-parameter)=
 `--delete-after-download`
 
-:   If specified, assets downloaded locally will be deleted in iCloud (actually moved to Recently Deleted album).
+:   If specified, assets downloaded locally will be deleted in iCloud (actually moved to Recently Deleted album). Deprecated, use [`--keep-icloud-recent-days`](keep-icloud-recent-days-parameter) instead
 
-    ```{seealso}
-    [Modes of operation](mode)
+    ```{note}
+    If remote assets were not downloaded, e.g. because they were already in local storage, they will NOT be deleted in iCloud.
+    ```
+
+    ```{versionadded} 1.21.0
+    ```
+
+    ```{deprecated} 1.26.0
     ```
 
 (keep-icloud-recent-days-parameter)=
 `--keep-icloud-recent-days X`
 
-:   If specified along with `--delete-after-download`, assets downloaded locally will not be deleted in iCloud if they were created within the specified number of days.
+:   Deletes assets in iCloud after they were downloaded or confirmed present locally, except the ones taken within the specified number of days. If set to 0, all photos will be deleted from iCloud.
+
+:   If any filters are used, e.g. [`--skip-videos`](skip-videos-parameter), then assets excluded from processing by filters are not subject to deletion from iCloud. For example, running icloudpd with [`--skip-videos`](skip-videos-parameter) on a huge iCloud collection of videos will download and delete nothing.
+
+:   Timestamp when the assets was taken (aka "created date") as reported by iCloud is used for calculating age of the asset. For example, asset taken in 2000, but added to iCloud in 2024, will be 25 years old in 2025. Same timestamp is used for the folder structure in the current system.
+
+    ```{seealso}
+    [Modes of operation](mode)
+
+    [Folder Structure](folder_structure)
+    ```
 
 (only-print-filenames-parameter)=
 `--only-print-filenames`