devel-docs: update icons.txt and icon theme section in README.

devel-docs/README.md

@@ -223,6 +223,24 @@ Alternatively GIMP supports the SVG Gradient format.
 ### Themes
 ### Icon themes
 
+Icon sets (a.k.a. "icon themes") have been separated from themes since
+GIMP 2.10 so you can have any icon theme with any theme.
+
+We currently only support 2 such icon themes — Symbolic and Color — and
+we keep around the Legacy icons.
+
+We don't want too many alternative designs as official icon themes
+(people are welcome to publish their favorite designs as third-party
+icons) though we would welcome special-purpose icon themes (e.g. high
+contrast).
+
+We also welcome design updates as a whole (anyone willing to work on
+this should discuss with us and propose something) and obviously fixes
+on existing icons or adding missing icons.
+
+See the dedicated [icons.txt](icons.txt) document for more technical
+information.
+
 ### Tool presets
 
 

devel-docs/icons.txt

@@ -6,32 +6,25 @@ Icon themes for GIMP
 Released Themes
 ---------------
 
-GIMP 2.10 comes with 4 icon themes:
+GIMP 3.0 comes with 3 icon themes:
+
+(1) Symbolic: the default icon theme which is vector and which will be
+automatically recolored to your theme colors.
 
-(1) Symbolic: the default icon theme (made for dark themes).
 We follow GNOME guidelines when possible:
-https://developer.gnome.org/hig/stable/icons-and-artwork.html.en
+https://developer.gnome.org/hig/guidelines/ui-icons.html
 
-(2) Symbolic-Inverted: programmatically generated from the "Symbolic"
-icon theme by inverting colors. Icon designers should not create icons
-specifically for "Symbolic-Inverted".
+(2) Color: the color icon theme, also designed with vector graphics, yet
+it won't be recolored.
 
-Note: exceptions on the icon generation can be applied.
-For instance "gimp-default-colors" and "gimp-toilet-paper" icons are not
-inverted. And "gimp-color-picker-black" is generated by inverting
-"gimp-color-picker-white" and reciprocally.
-Ask for developer help when such exceptions are needed.
-
-(3) Color: a new color icon theme, also designed with vector graphics.
-
-(4) Legacy: this icon theme which contains the old GIMP 2.8 icons. It is
-not maintained anymore and we are not expecting new icons for Legacy.
-Yet since we keep them in the source tree for now, we would accept
-updates.
+(3) Legacy: icon theme which contains the old GIMP 2.8's raster icons.
+It is not maintained anymore and we are not expecting new icons for
+Legacy. Yet since we keep them in the source tree for now, we would
+accept updates.
 
 The Symbolic icon theme are our main target since they are considered
 better suited for graphics work (less visual distraction). Color icons
-are kept as fall-over since some users still prefer them.
+are kept as fall-back since some users prefer them.
 
 ----------------
 Adding new icons
@@ -62,10 +55,19 @@ yet a reliable way to extract icons out of the single SVG file without
 using crazy build dependencies (like Inkscape). So this is done by hand
 for the time being.
 
-- Add the icons in `icons/icon-list.mk`.
-This file is shared by all 3 maintained icon themes (Symbolic,
-Symbolic-Inverted and Color), so you must make sure that you have the
-Symbolic as well as the Color icons drawn before adding them.
+Please make sure that you provide both the Symbolic as well as the Color
+icons. You are welcome to add a raster version for Legacy, but this is
+not mandatory anymore.
+
+- Add the icons in `icons/Symbolic/icon-list.mk` and
+  `icons/Color/icon-list.mk`.
+
+TODO: a single file used to be shared by the maintained icon themes
+(Symbolic and Color now) but this is not the case anymore because of how
+icons are handled in GTK3. We should bring back such logic of shared
+list, but also usable both in meson and autotools. Otherwise we are
+stuck in maintenance mess with inconsistent builds and installations.
+
 
 Pixel perfection
 ----------------
@@ -90,6 +92,40 @@ have 2 pixel-perfect versions.
 - if time is missing, creating the smaller size only is a first step
 and is acceptable.
 
+Colors in Symbolic icon theme
+-----------------------------
+
+By default, colors in the Symbolic icon theme don't matter as they will
+be changed by the foreground and background colors of the theme. Yet it
+is still a good idea to use the same colors for all icons in
+`icons/Symbolic/symbolic-scalable.svg` to keep visual consistency when
+reviewing icons.
+
+Furthermore, there is a trick to apply hard-coded colors (i.e. which
+won't be recolored): add the `!important` flag to the color in the
+`style` SVG parameter. Then GTK will not recolor this color.
+
+It is to be noted that (last we tested), Inkscape was not able to keep
+this flag, so you will likely have to edit the file manually in a text
+or XML editor.
+
+For instance "[gimp-default-colors](icons/Symbolic/scalable/gimp-default-colors-symbolic.svg)"
+and "[gimp-toilet-paper](icons/Symbolic/scalable/gimp-toilet-paper-symbolic.svg)"
+icons contain such tricks.
+For the first one, the default colors was black and white in this
+specific order (it made no sense to invert them or worse to transform
+them into whatever other colors the theme might be using). For the
+second, it was considered inappropriate by some contributors to generate
+black toilet papers.
+
+Other such examples are
+[gimp-color-picker-black](icons/Symbolic/scalable/gimp-color-picker-black-symbolic.svg),
+[gimp-color-picker-gray](icons/Symbolic/scalable/gimp-color-picker-gray-symbolic.svg)
+and
+[gimp-color-picker-white](icons/Symbolic/scalable/gimp-color-picker-white-symbolic.svg).
+Since they are designing specific colors, it doesn't make sense to let
+any recoloring happen.
+
 Sizes
 -----