docs: Document remote icon download and caching

Author: joebonrichie

docs/asgen-config.md

@@ -67,8 +67,9 @@ Note that this example assume that your packages are located in directories
 | ExportDirs            | Set where to export data. The dictionary requires full paths set for the "Media", "Data", "Hints" or "Html" key. In case a value is missing, the default locations are used.                   |
 | ExtraMetainfoDir      | Path to a directory where additional injected metainfo files are located. If not set, the `extra-metainfo` directory in the project workspace is used.                                         |
 | WorkspaceDir          | Explicitly set the location of the workspace. Only makes sense if the generator is meant to be used with a lot of configuration files and the configuration is passed to it via the `-c` flag. |
-| Icons                 | Customize the icon policy. See below for more details.                                                                                                                                         |
-| MaxScreenshotFileSize | The maximum size of downloaded screenshot image or video files in MiB. `0` means unlimited. *Default: `14`*                                                                                    |
+| Icons                 | Customize the icon policy. See below for more details.                                                                                                                                       |
+| MaxScreenshotFileSize | The maximum size of downloaded screenshot image, video files or remote icons in MiB. `0` means unlimited. *Default: `14`*
+|
 
 ### Suite fields
 
@@ -93,7 +94,7 @@ If no explicit value is set for a feature, the generator will pick its default v
 |----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | validateMetainfo           | Validate the AppStream upstream metadata. The validation is slow, but will produce better feedback and issue hints if enabled. *Default: `ON`*                                                                                                                                                |
 | processDesktop             | Process .desktop files which do not have a metainfo file. If disabled, all data without metainfo file will be ignored. *Default: `ON`*                                                                                                                                                        |
-| noDownloads                | Do not attempt any downloads. This will implicitly disable any handling of screenshots and possibly other features. Using this flag is discouraged. *Default: `OFF`*                                                                                                                          |
+| noDownloads                | Do not attempt any downloads. This will implicitly disable any handling of screenshots, remote icon downloads and possibly other features. Using this flag is discouraged. *Default: `OFF`*                                                                                                                          |
 | createScreenshotsStore     | Mirror screenshots and create thumbnails of them in `media/`. This will yield the best experience with software-centers, and also allow full control over which screenshots are displayed. Disabling this will make clients pull screenshots from 3rd-party upstream servers. *Default: `ON`* |
 | optimizePNGSize            | Use `optipng` to reduce the size of PNG images. Optipng needs to be installed. *Default: `ON`*                                                                                                                                                                                                |
 | metadataTimestamps         | Write timestamps into generated metadata files. *Default: `ON`*                                                                                                                                                                                                                               |
@@ -119,6 +120,11 @@ cache of all icons exists. Icon sizes not mentioned, or with both `cached` and `
 The `64x64` icon size must always be present and be cached. If this is not the case, appstream-generator will adjust the configuration internally and emit a warning.
 If no `Icons` field is present, appstream-generator will use a default policy for icons (creating cache tarballs for all sizes, and remote links for sizes >= 129x128px).
 
+Additionally, if a component's MetaInfo file declares a remote icon (an `<icon type="remote">` tag with a URL), the generator will download that icon and store it in the
+media export directory, like icons extracted from packages. This means the icon ends up in the generated icon tarballs as well (for icon sizes with `cached` set to `true`).
+Remote icon downloads are skipped if the `noDownloads` feature is enabled, and respect the `MaxScreenshotFileSize` limit. If a remote icon cannot be downloaded, the
+original remote icon URL is kept in the metadata as a fallback, so clients can still fetch the icon from upstream.
+
 ## Injecting extra metainfo / removing components
 
 Sometimes injecting metainfo files directly into the generation process instead of packaging them makes sense. This can be done for example for `web-application` components, `operating-system` components