[Doxygen] More picture docs (#7220)

* [Doxygen] More picture docs

Took 12 minutes

Took 8 minutes

* [Doxygen] Move custom card pictures page into card_pictures subfolder

The actual cyclic dependency fix is converting the mutual @subpage
reference from custom_card_pictures to fixing_card_pictures into a
plain @ref, so the page hierarchy no longer loops back on itself.

* [Doxygen] Correct card-picture docs per review

* fix table layout

* [Doxygen] Deduplicate placeholder table and document image overrides

- Make custom_card_pictures.md the canonical home of the URL reference-point
  table; loading_card_pictures.md cross-references it through @ref instead of
  maintaining a second copy (unaddressed review comment).
- Switch the remaining @subpage custom_card_pictures to @ref in
  fixing_card_pictures.md so the page keeps its single parent under
  user_reference.
- Document the Image Overrides feature added in #7311/#7312 on the user page,
  loading_card_pictures.md and fixing_card_pictures.md: local override storage,
  the downloadedPics root lookup, exact file-name matching, and the set-folder
  vs flat export naming schemes.

* Update doc/doxygen/extra-pages/user_documentation/card_pictures/custom_card_pictures.md

Co-authored-by: tooomm <tooomm@users.noreply.github.com>

---------

Co-authored-by: Lukas Brübach <Bruebach.Lukas@bdosecurity.de>
Co-authored-by: tooomm <tooomm@users.noreply.github.com>

doc/doxygen/extra-pages/user_documentation/card_pictures/custom_card_pictures.md

@@ -0,0 +1,135 @@
+@page custom_card_pictures Custom Card Pictures
+
+There are four ways to make Cockatrice use custom artwork for your cards:
+
+- Placing image files in the **CUSTOM pictures folder**.
+- Providing a **custom card database** that points each printing at a picture URL via the `picurl` property.
+- Writing your **own download URL templates**.
+- Setting an **image override** for a single card from inside the deck editor.
+
+Each of these is described below. If pictures are missing or wrong, see @ref fixing_card_pictures instead.
+
+# Custom Pictures Folder (CUSTOM)
+
+Any image file placed in the CUSTOM folder is used as the card picture, and no download is attempted for cards that
+match a file there.
+
+- The folder is `<pictures directory>/CUSTOM/`. The pictures directory is configured on the 'General' settings tab,
+  under 'Directories' → 'Pictures directory'.
+- Any image format Qt can decode is accepted (PNG, JPG/JPEG, WebP, GIF, BMP, ...); the file extension is not filtered,
+  so even an extension-less file is picked up if the decoder recognizes its content.
+- Files are indexed by their name, so you can organize them into subfolders freely.
+- New or changed files are picked up automatically within a few seconds — no client restart is required.
+
+The file name must match the card using one of the naming schemes below. Both `_` and `-` are accepted as separators,
+and the file extension is ignored when matching:
+
+| Scheme                      | Example file name                                       |
+| --------------------------- | ------------------------------------------------------- |
+| Card Name                   | `Example Card.png`                                      |
+| Card Name + Set             | `Example Card_DDL.png`                                  |
+| Card Name + Set + Collector | `Example Card_DDL_43.png`                               |
+| Set + Collector + Card Name | `DDL_43_Example Card.png`                               |
+| Card Name + Provider ID     | `Example Card_0b23cdc8-d413-4fb1-8470-474221b10fe2.png` |
+
+The name used for matching is the *corrected* card name. Correction removes the split-card separator ` // ` and the
+characters reserved in Windows file names (`* < > : " \ ?` and control characters), and turns `/` into a space, so the
+"Example // Card" card is matched by a file named `ExampleCard.png`, not `Example // Card.png`. Most other punctuation
+(commas, apostrophes, `!`, ...) is left untouched.
+
+\attention A file in the CUSTOM folder always wins over downloaded pictures, even if it is the wrong image. Delete the
+file if you want to see the downloaded artwork again.
+
+The naming conventions are the same as those recognized in the set-named subfolders and in `downloadedPics`, and are
+documented for developers in @ref loading_card_pictures.
+
+# Custom Card Database (picurl)
+
+If you maintain your own card database (see the
+[Custom Cards & Sets](https://github.com/Cockatrice/Cockatrice/wiki/Custom-Cards-&-Sets) wiki), each printing's `<set>`
+tag can carry a `picurl` attribute containing a full URL for that printing's picture:
+
+```xml
+<set picurl="https://example.com/cards/example-card.jpg" ...>
+```
+
+Cockatrice tries this URL **before** the configured download URL templates, so it is the most direct way to provide
+custom artwork for a specific printing.
+
+- The URL should start with `http://` or `https://`; the scheme is not validated, so make sure it is absolute or the
+  download may silently fail.
+- When you change a `picurl` for a card whose picture was already downloaded and cached, delete the stored images
+  (Storage tab → 'Delete Saved Images' / 'Delete Cached Images') so Cockatrice fetches the new URL.
+
+# Custom Download URL Templates
+
+The built-in download URLs are templates: Cockatrice replaces reference points in the URL with information about the
+card and its printing. You can write your own templates in 'Cockatrice → Settings' (Ctrl + Shift + P by default), on
+the 'Deck Editor' tab, in the 'URL Download Priority' section.
+
+The following reference points are available:
+
+| Reference point                 | Description                     | Example        |
+| ------------------------------- | ------------------------------- | -------------- |
+| `!name!`                        | Card name                       | `Example Card` |
+| `!name_lower!`                  | Card name, lower case           | `example card` |
+| `!corrected_name!`              | Corrected card name             | `ExampleCard` (instead of "Example // Card") |
+| `!corrected_name_lower!`        | Corrected card name, lower case | `examplecard`  |
+| `!sflang!`                      | Scryfall language code for the current client language; defaults to English when the language has no localized images | `en`, `zhs` |
+| `!setcode!` / `!setcode_lower!` | Set code                        | `EXM` / `exm`  |
+| `!setname!` / `!setname_lower!` | Full set name                   | `Exemplary Set` / `exemplary set` |
+| `!set:<property>!`              | A property of this printing, e.g. `muid` (Gatherer multiverse ID), `uuid` (Scryfall UUID), `num` (collector number), `rarity` | `373549` |
+| `!prop:<property>!`             | A property of the card, e.g. `side` (front/back), `colors`, `cmc`, `coloridentity`, `type`, `pt`, and the format legality statuses | `front` |
+
+The `!set:...!` and `!prop:...!` reference points support two modifiers:
+
+- `_fill_with_<text>` pads the value with the given text, right-aligned, e.g. `!set:num_fill_with_000!` turns collector
+  number `1` into `001`. If the value is longer than the fill text, the template is skipped.
+- `_substr_<start>_<length>` extracts a substring, e.g. `!set:num_substr_2_2!` takes two characters starting at the
+  third. If the substring would extend past the end of the value, the template is skipped.
+
+Substituted values are URL-encoded. A template that asks for a property the card or printing does not have is skipped,
+and the next template in the list is tried instead.
+
+\attention Custom URLs should start with `http://` or `https://`. As with `picurl`, the scheme is not validated before
+the URL is handed to QNetworkAccessManager, so use an absolute URL or the download may silently fail.
+
+Some working examples:
+
+```text
+https://cards.scryfall.io/large/!prop:side!/!set:uuid_substr_0_1!/!set:uuid_substr_1_1!/!set:uuid!.jpg
+https://api.scryfall.com/cards/!set:uuid!?format=image&face=!prop:side!
+https://api.scryfall.com/cards/multiverse/!set:muid!?format=image
+https://gatherer.wizards.com/Handlers/Image.ashx?multiverseid=!set:muid!&type=card
+https://gatherer.wizards.com/Handlers/Image.ashx?name=!name!&type=card
+```
+
+See the [Custom Picture Download URLs](https://github.com/Cockatrice/Cockatrice/wiki/Custom-Picture-Download-URLs)
+wiki for more examples and ideas.
+
+\attention Keep in mind that templates using `!name!` or `!set:muid!` resolve by name or multiverse ID, not by the
+exact printing. Only the Scryfall `!set:uuid!` templates always return the exact printing requested. See
+@ref fixing_card_pictures for more on this.
+
+# Image Overrides
+
+The quickest way to give one card custom art is an image override: right-click the card in the deck editor's printing
+selector and open the **Image Overrides** submenu of the context menu.
+
+- **Load Custom Image...** — choose a picture file (the dialog suggests PNG, JPG/JPEG and WebP); it becomes that card's
+  artwork immediately.
+- **One entry per alternate printing** of the card, labeled `<set> <collector number>` (hovering an entry previews that
+  printing's artwork). Selecting one makes the card use that exact printing's picture, so e.g. a basic land can be shown
+  with any of its artworks.
+- **Clear Custom Image** — removes the stored override and returns the card to normal resolution. It is only available
+  while the card has a stored override.
+
+Overrides are stored as `.png` files in `<pictures directory>/downloadedPics/`, under the "Naming scheme" configured on
+the Storage settings page, and are matched the same way as downloaded images. Because local files are checked before any
+URL is requested, an override always wins over downloaded artwork and `picurl` for that card. The override exists only on
+the machine it was created on - it is not part of the deck file - so a card with a stored override shows normally on
+another computer.
+
+\attention If you also keep a matching file in the CUSTOM folder, that file is matched before the override. When you
+change an override, use **Clear Custom Image** so the stored `.png` is replaced; manually deleting the file in
+`downloadedPics/` has the same effect.

doc/doxygen/extra-pages/user_documentation/index.md

@@ -11,6 +11,10 @@
 
 - @subpage beta_release
 
+## Card Pictures
+
+- @subpage custom_card_pictures
+
 ## Troubleshooting
 
 - @subpage fixing_card_pictures

doc/doxygen/extra-pages/user_documentation/troubleshooting/fixing_card_pictures.md

@@ -28,7 +28,8 @@ valid URLs. If you suspect the list has been modified or corrupted, press 'Reset
 defaults.
 
 For information on how to add your own custom URL templates, see the 'How to add a custom URL' link in the same
-settings section.
+settings section, or @ref custom_card_pictures for a full reference of the URL reference points, the CUSTOM
+pictures folder, and custom card databases.
 
 # Check Your Local Picture Folder
 
@@ -41,8 +42,12 @@ Cockatrice checks the following locations, in order:
 - The custom pictures folder (recursively indexed by file name).
 - `<pictures directory>/<set code>/<card file name>`
 - `<pictures directory>/downloadedPics/<set code>/<card file name>`
+- `<pictures directory>/downloadedPics/<card file name>` (for export naming schemes without a set folder)
 
-The following import naming schemes are recognized (using both `_` and `-` as separators):
+A file only matches when its name without the extension equals one of the recognized scheme patterns exactly.
+
+The following import naming schemes are recognized (using both `_` and `-` as separators). The canonical table with
+concrete example file names is on @ref custom_card_pictures:
 
 | Scheme                      | Pattern                    |
 | --------------------------- | -------------------------- |
@@ -56,6 +61,10 @@ If a picture you downloaded or placed manually is wrong, stale, or corrupted, de
 attention to the `downloadedPics` subfolder: this is where the filesystem caching method writes downloaded images, and
 after a provider outage it can permanently contain the wrong printing until you delete it manually.
 
+If a card persistently shows artwork you assigned yourself, you may have an **image override** set for it. Right-click
+the card in the deck editor's printing selector and use 'Image Overrides' → 'Clear Custom Image' to remove it (or
+delete the stored `.png` in `downloadedPics/`). See @ref custom_card_pictures for details.
+
 See @ref loading_card_pictures for details on how local images are loaded.
 
 # Clear Caches