From 91ab260ba339602cb3b1716d7dfcf0032be21dcd Mon Sep 17 00:00:00 2001
From: Bruno Haible <bruno@clisp.org>
Date: Sun, 6 Oct 2024 03:27:19 +0200
Subject: [PATCH] its: Improve comments in *.its files.

* gettext-tools/its/glade2.its: Improve comments.
* gettext-tools/its/gtkbuilder.its: Likewise.
* gettext-tools/its/gsettings.its: Likewise.
* gettext-tools/its/metainfo.its: Likewise.
---
 gettext-tools/its/glade2.its     |  6 ++++++
 gettext-tools/its/gsettings.its  |  5 +++++
 gettext-tools/its/gtkbuilder.its | 10 +++++++++-
 gettext-tools/its/metainfo.its   |  5 +++++
 4 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/gettext-tools/its/glade2.its b/gettext-tools/its/glade2.its
index 48220f302..8b38db750 100644
--- a/gettext-tools/its/glade2.its
+++ b/gettext-tools/its/glade2.its
@@ -19,6 +19,12 @@
 <its:rules xmlns:its="http://www.w3.org/2005/11/its"
            xmlns:gt="https://www.gnu.org/s/gettext/ns/its/extensions/1.0"
            version="2.0">
+
+  <!-- Documentation of the Glade 2 XML file format:
+       https://download.gnome.org/sources/libglade/2.6/libglade-2.6.4.tar.gz
+       file libglade-2.6.4/doc/html/libglade-dtd.html
+  -->
+
   <its:translateRule selector="/glade-interface" translate="no"/>
   <its:translateRule
       selector="/glade-interface//property[@translatable = 'yes'] |
diff --git a/gettext-tools/its/gsettings.its b/gettext-tools/its/gsettings.its
index c69f1d2f4..fe963846b 100644
--- a/gettext-tools/its/gsettings.its
+++ b/gettext-tools/its/gsettings.its
@@ -19,6 +19,11 @@
 <its:rules xmlns:its="http://www.w3.org/2005/11/its"
            xmlns:gt="https://www.gnu.org/s/gettext/ns/its/extensions/1.0"
            version="2.0">
+
+  <!-- Documentation of the GSettings XML file format:
+       https://docs.gtk.org/gio/class.Settings.html
+  -->
+
   <its:translateRule selector="/schemalist" translate="no"/>
 
   <its:translateRule selector="//summary | //description" translate="yes"/>
diff --git a/gettext-tools/its/gtkbuilder.its b/gettext-tools/its/gtkbuilder.its
index a984511d5..9d28531a7 100644
--- a/gettext-tools/its/gtkbuilder.its
+++ b/gettext-tools/its/gtkbuilder.its
@@ -19,8 +19,16 @@
 <its:rules xmlns:its="http://www.w3.org/2005/11/its"
            xmlns:gt="https://www.gnu.org/s/gettext/ns/its/extensions/1.0"
            version="2.0">
+
+  <!-- Documentation of the GtkBuilder XML file format:
+       https://docs.gtk.org/gtk3/class.Builder.html
+       https://docs.gtk.org/gtk4/class.Builder.html
+       A better documentation does not exist; see
+       https://gitlab.gnome.org/GNOME/gtk/-/issues/4039 .
+  -->
+
   <its:translateRule selector="/interface" translate="no"/>
-  <!-- https://developer-old.gnome.org/gtk4/stable/GtkBuilder.html says about
+  <!-- https://docs.gtk.org/gtk4/class.Builder.html says about
        boolean attribute values:
        "strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted as TRUE,
         strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted as FALSE"
diff --git a/gettext-tools/its/metainfo.its b/gettext-tools/its/metainfo.its
index 466c250a3..ec0fb7df6 100644
--- a/gettext-tools/its/metainfo.its
+++ b/gettext-tools/its/metainfo.its
@@ -19,6 +19,11 @@
 <its:rules xmlns:its="http://www.w3.org/2005/11/its"
            xmlns:gt="https://www.gnu.org/s/gettext/ns/its/extensions/1.0"
            version="2.0">
+
+  <!-- Documentation of the *.metainfo.xml file format:
+       https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html
+  -->
+
   <its:translateRule selector="/component" translate="no"/>
   <its:translateRule selector="/component/name |
                                /component/summary |