[gimp-extensions-web] docs: committing an old update.

[Jehan <jehanp src gnome org>]

commit 3da113055859bb3312ea08594e0caba613f3b804
Author: Jehan <jehan girinstud io>
Date:   Tue Jan 12 16:17:01 2021 +0100

    docs: committing an old update.
    
    So I discover that I hadn't committed some old changes (probably more
    than a year old!). Doing so now.

 docs/README | 163 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 162 insertions(+), 1 deletion(-)
---
diff --git a/docs/README b/docs/README
index 11db1af..14a97ab 100644
--- a/docs/README
+++ b/docs/README
@@ -104,6 +104,93 @@ be done silently and would require approval):
 </requires>
 ```
 
+#### Examples
+##### A brush extension
+
+A simple set of brushes only, which are stored under the subdirectory
+`brushes/`.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<component type="addon">
+  <id>org.example.nature_brushes</id>
+  <extends>org.gimp.GIMP</extends>
+
+  <name>Nature brush set</name>
+  ⁠<developer_name>Awesome team</developer_name>
+  <summary>A collection of brushes to draw natural elements</summary>
+  <description>
+    <p>This collection contains many brushes specifically to draw
+    natural elements:</p>
+    <ul>
+      <li>Leaves</li>
+      <li>Clouds</li>
+      <li>Dirt</li>
+    </ul>
+  </description>
+
+  <url type="homepage">https://example.org/nature_brushes</url>
+  <url type="donation">https://example.org/donate</url>
+
+  <metadata_license>CC0-1.0</metadata_license>
+  <project_license>CC0-1.0</project_license>
+
+  <releases>
+    <release version="0.2" date="2019-02-19" />
+    <release version="0.1" date="2018-06-07" />
+  </releases>
+  <metadata>
+    <value key="GIMP::brush-path">brushes</value>
+  </metadata>
+</component>
+```
+
+##### A plug-in
+
+This plug-in requires the brush extension (version 0.2 or higher) to be
+installed too so it adds a requirement. Also it requires GIMP 2.10.6 or
+higher (maybe because it uses some new API), and lesser than GIMP 3.0
+(API change, the plug-in won't work).
+
+This will allow to pull an extension dependency (i.e. another extension)
+after warning the user it will do so, and also warn/disable extensions
+when we know an extension won't work (an application can then propose to
+check if updates of the extensions are available).
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<component type="addon">
+  <id>org.example.tree_generator</id>
+  <extends>org.gimp.GIMP</extends>
+
+  <name>Generator of trees</name>
+  <summary>Plug-in randomly generating trees</summary>
+  <description>
+    <p>This plug-in will randomly generate a forest inside the
+    selection.</p>
+  </description>
+
+  <url type="homepage">https://example.org/tree_generator</url>
+  <url type="donation">https://example.org/donate</url>
+
+  <metadata_license>CC0-1.0</metadata_license>
+  <project_license>GPL-3.0+</project_license>
+
+  <releases>
+    <release version="0.1" date="2019-02-20" />
+  </releases>
+  <requires>
+    <!-- Uses an API appeared in 2.10.6. -->
+    <id version="2.10.6" compare="ge">org.gimp.GIMP</id>
+    <id version="3.0.0" compare="lt">org.gimp.GIMP</id>
+    <id version="0.2" compare="ge">org.example.nature_brushes</id>
+  </requires>
+  <metadata>
+    <value key="GIMP::plug-in-path">src/tree-generator.py</value>
+  </metadata>
+</component>
+```
+
 ## Support in GIMP
 ### Repositories
 
@@ -112,11 +199,85 @@ default. There is probably no reason to forbid third-party repositories
 so these could be supported (added through GIMP Preferences).
 
 GIMP will simply download a static file from an extension repository,
-which will contain the metadata for all available extensions.
+which will contain the concatenated metadata for all available
+extensions.
 
 Of course some layers of security would be needed (certificates,
 checksums, signed packages…).
 
+#### Example
+
+Our repository containing only the 2 extensions above will serve the
+following file:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<components version="0.12">
+  <component type="addon">
+    <id>org.example.nature_brushes</id>
+    <extends>org.gimp.GIMP</extends>
+
+    <name>Nature brush set</name>
+    <developer_name>Awesome team</developer_name>
+    <summary>A collection of brushes to draw natural elements</summary>
+    <description>
+      <p>This collection contains many brushes specifically to draw
+      natural elements:</p>
+      <ul>
+        <li>Leaves</li>
+        <li>clouds</li>
+        <li>dirt</li>
+      </ul>
+    </description>
+
+    <url type="homepage">https://example.org/nature_brushes</url>
+    <url type="donation">https://example.org/donate</url>
+
+    <metadata_license>CC0-1.0</metadata_license>
+    <project_license>CC0-1.0</project_license>
+
+    <releases>
+      <release version="0.2" date="2019-02-19" />
+      <release version="0.1" date="2018-06-07" />
+    </releases>
+    <metadata>
+      <value key="GIMP::brush-path">brushes</value>
+    </metadata>
+  </component>
+
+  <component type="addon">
+    <id>org.example.tree_generator</id>
+    <extends>org.gimp.GIMP</extends>
+
+    <name>Generator of trees</name>
+    <summary>Plug-in randomly generating trees</summary>
+    <description>
+      <p>This plug-in will randomly generate a forest inside the
+      selection.</p>
+    </description>
+
+    <url type="homepage">https://example.org/tree_generator</url>
+    <url type="donation">https://example.org/donate</url>
+
+    <metadata_license>CC0-1.0</metadata_license>
+    <project_license>GPL-3.0+</project_license>
+
+    <releases>
+      <release version="0.1" date="2019-02-20" />
+    </releases>
+    <requires>
+      <!-- Uses an API appeared in 2.10.6. -->
+      <id version="2.10.6" compare="ge">org.gimp.GIMP</id>
+      <id version="3.0.0" compare="lt">org.gimp.GIMP</id>
+      <id version="0.2" compare="ge">org.example.nature_brushes</id>
+    </requires>
+    <metadata>
+      <value key="GIMP::plug-in-path">src/tree-generator.py</value>
+    </metadata>
+  </component>
+</components>
+```
+
 ### Dedicated GUI
 
 The GUI would allow searching (through extension names, descriptions,