From 07a785eb02848af691e5f02b216ce6a9c1e55e3c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pablo=20Correa=20G=C3=B3mez?= <ablocorrea@hotmail.com>
Date: Sun, 29 Jan 2023 16:33:14 +0100
Subject: [PATCH] docs: Clarify the locations where catalog icons should be
 placed

Rationale: https://gitlab.gnome.org/GNOME/gnome-software/-/merge_requests/1574#note_1625290

Co-authored-by: Matthias Klumpp <matthias@tenstral.net>
---
 docs/xml/catalog-iconcache.xml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/xml/catalog-iconcache.xml b/docs/xml/catalog-iconcache.xml
index ad180751..c01c9f82 100644
--- a/docs/xml/catalog-iconcache.xml
+++ b/docs/xml/catalog-iconcache.xml
@@ -20,9 +20,11 @@
 	<section id="spec-iconcache-location">
 		<title>Filesystem locations</title>
 		<para>
-			All icons of type <literal>cached</literal> must be placed in <filename>/usr/share/swcatalog/icons/%{origin}/%{size}/</filename> or <filename>/var/cache/swcatalog/icons/%{origin}/%{size}/</filename>,
+			All icons of type <literal>cached</literal> must be placed in <filename>/usr/share/swcatalog/icons/%{origin}/%{size}/</filename> or <filename>/var/(lib|cache)/swcatalog/icons/%{origin}/%{size}/</filename>,
 			where <literal>origin</literal> is the AppStream data origin defined in the AppStream data file (see <xref linkend="spec-asxml-general"/>), and <literal>size</literal>
 			is <code>64x64</code> or <code>128x128</code> depending on the size of the icon. And icon might be present with different sizes in both directories.
+			When finding cached icons, they must only be searched for in the same location where the accompanying catalog metadata is located.
+			For example, icons for <filename>/var/lib/swcatalog/xml/debian-jessie-main.xml.gz</filename> must only be looked up in <filename>/var/lib/swcatalog/icons/debian-jessie-main/</filename> and not also in locations in <filename>/var/cache/</filename> or elsewhere.
 		</para>
 		<para>
 			For example the cache icon <code>krita.png</code> of a component in a data file with the origin <code>jessie</code> should be stored in