Provide XML schemas for .its and .loc files.

Suggested by Martin Blanchard <tchaik@gmx.com>
at <https://savannah.gnu.org/bugs/?56519>.

* gettext-tools/src/its.xsd: New file, reverse-engineered from its.c.
* gettext-tools/src/its-extensions.xsd: New file, reverse-engineered from its.c.
* gettext-tools/src/locating-rules.xsd: New file, reverse-engineered from
locating-rules.c.
* gettext-tools/src/Makefile.am (schemadir): New variable.
(schema_DATA): New variable.
(EXTRA_DIST): Distribute all of schema_DATA.
* gettext-tools/configure.ac: Check for xmllint, and set XMLLINT.
* gettext-tools/its/Makefile.am (ITS_FILES, LOC_FILES): New variables.
(dist_its_DATA): Rewrite.
(check-local): New rule.
* gettext-tools/doc/gettext.texi (Preparing ITS Rules): Split into two
subsections. Mention which schema the files have to obey.
* HACKING: Mention xmllint as maintainer prerequisite.
* PACKAGING: Mention the $prefix/share/gettext/schema/ directory.
* NEWS: Mention the change.

diff --git a/HACKING b/HACKING
index 6919ff23b63489624b2971ec043c1aa1d9e8bbd9..b29b4ab887c7cc5f942b7b484ed28fba1dbbef5a 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -141,6 +141,13 @@ Additional requirements for maintainers
 If you are a maintainer, you will want to minimize the number of tests that
 are skipped. To this effect, you need to install also:
 
+  * The xmllint program
+    + Homepage: https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home
+    + Pre-built package name:
+      - On Debian and Debian-based systems: libxml2-utils,
+      - On Red Hat distributions: libxml2.
+      - Other: https://repology.org/project/libxml2/versions
+
   * A C++ compiler
     + Homepage: https://gcc.gnu.org/
     + Pre-built package name:

diff --git a/NEWS b/NEWS
index 3961ba2e18f7fd37a3d0108606ce42f045929eab..88bbdde6008c785c947160aeb462bcf78d4cbe82 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,7 @@
 Version 0.23 - September 2024
 
 * Programming languages support:
+  - XML: XML schemas for .its and .loc files are now provided.
   - Python:
     o xgettext now assumes source code for Python 3 rather than Python 2.
       This affects the interpretation of escape sequences in string literals.

diff --git a/PACKAGING b/PACKAGING
index d6df1fc46a86375f28329a8d563481b1baf1e463..942309c33db068b667ae2effb1fc77ee57c9e62b 100644 (file)
--- a/PACKAGING
+++ b/PACKAGING
@@ -133,6 +133,7 @@ is according to the following file list.
       $prefix/share/gettext/config.rpath
       $prefix/share/gettext/po/*
       $prefix/share/gettext/projects/*
+      $prefix/share/gettext/schema/*
       $prefix/share/gettext/styles/*
       $prefix/share/gettext/gettext.h
       $prefix/share/gettext/gettext.jar

diff --git a/gettext-tools/configure.ac b/gettext-tools/configure.ac
index 4fb68a6a122e7346d4a15fd187d2a66ef95f3240..1542d9ba651d09975007cb7fffe964e38715e884 100644 (file)
--- a/gettext-tools/configure.ac
+++ b/gettext-tools/configure.ac
@@ -592,6 +592,9 @@ dnl Check whether to execute tests of the system (vendor-provided) libintl API.
 dnl We execute these tests if and only if we don't install our own libintl.
 AM_CONDITIONAL([TEST_SYSTEM_LIBINTL], [test $USE_INCLUDED_LIBINTL = no])
 
+dnl Checks for optional programs for the its/* tests.
+AC_PATH_PROGS([XMLLINT], [xmllint], [:])
+
 AC_CONFIG_SUBDIRS([examples])
 
 AC_CONFIG_FILES([Makefile],

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 88096771faf1cb8c049109585b0d17c4876a5518..e70b9e57bfb3396752f84f9c2dc49d66a5667787 100644 (file)
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -487,6 +487,11 @@ Internationalizable Data Formats
 * AppData::                     AppData - freedesktop.org application description
 * Preparing ITS Rules::         Preparing Rules for XML Internationalization
 
+Preparing Rules for XML Internationalization
+
+* ITS Rules::                   Specifying ITS Rules
+* Locating Rules::              Specifying where to find the ITS Rules
+
 Localized Data Formats
 
 * Editable Message Catalogs::   Editable Message Catalogs
@@ -10651,6 +10656,14 @@ appdata-tools, appstream, libappstream-glib-dev
 @subsection Preparing Rules for XML Internationalization
 @cindex preparing rules for XML translation
 
+@menu
+* ITS Rules::                   Specifying ITS Rules
+* Locating Rules::              Specifying where to find the ITS Rules
+@end menu
+
+@node ITS Rules
+@subsubsection Specifying ITS Rules
+
 Marking translatable strings in an XML file is done through a separate
 "rule" file, making use of the Internationalization Tag Set standard
 (ITS, @uref{https://www.w3.org/TR/its20/}).  The currently supported ITS
@@ -10751,9 +10764,16 @@ second ("A non-translatable string"), the following ITS rules can be used:
 </its:rules>
 @end example
 
-@samp{xgettext} needs another file called "locating rule" to associate
+ITS rules files must have the @file{.its} file extension and obey
+the XML schema encoded by
+@code{its.xsd} and its auxiliary schema @code{its-extensions.xsd}.
+
+@node Locating Rules
+@subsubsection Specifying where to find the ITS Rules
+
+@samp{xgettext} needs another file called "locating rules" to associate
 an ITS rule with an XML file.  If the above ITS file is saved as
-@file{messages.its}, the locating rule would look like:
+@file{messages.its}, the locating rules file would look like:
 
 @example
 <?xml version="1.0"?>
@@ -10779,18 +10799,19 @@ file.
 The first rule matches any file with the @file{.xml} file extension, but
 it only applies to XML files whose root element is @samp{<messages>}.
 
-The second rule indicates that the same ITS rule file are also
+The second rule indicates that the same ITS rules file are also
 applicable to any file with the @file{.msg} file extension.  The
 optional @code{name} attribute of @code{locatingRule} allows to choose
 rules by name, typically with @code{xgettext}'s @code{-L} option.
 
-The associated ITS rule file is indicated by the @code{target} attribute
+The associated ITS rules file is indicated by the @code{target} attribute
 of @code{locatingRule} or @code{documentRule}.  If it is specified in a
 @code{documentRule} element, the parent @code{locatingRule} shouldn't
 have the @code{target} attribute.
 
-Locating rule files must have the @file{.loc} file extension.  Both ITS
-rule files and locating rule files must be installed in the
+Locating rules files must have the @file{.loc} file extension and obey
+the XML schema encoded by @code{locating-rules.xsd}.
+Both ITS rules files and locating rules files must be installed in the
 @file{$prefix/share/gettext/its} directory.  Once those files are
 properly installed, @code{xgettext} can extract translatable strings
 from the matching XML files.

diff --git a/gettext-tools/its/Makefile.am b/gettext-tools/its/Makefile.am
index b33081efb29045a9ea107922278572692d6a3259..7c50961b9822811717846e115b90a1d73270f9b7 100644 (file)
--- a/gettext-tools/its/Makefile.am
+++ b/gettext-tools/its/Makefile.am
@@ -1,5 +1,5 @@
 ## Makefile for the gettext-tools/its subdirectory of GNU gettext
-## Copyright (C) 2015, 2017 Free Software Foundation, Inc.
+## Copyright (C) 2015-2024 Free Software Foundation, Inc.
 ##
 ## This program is free software: you can redistribute it and/or modify
 ## it under the terms of the GNU General Public License as published by
@@ -20,5 +20,28 @@ AUTOMAKE_OPTIONS = 1.2 gnits
 
 pkgdatadir = $(datadir)/gettext
 itsdir = $(pkgdatadir)$(PACKAGE_SUFFIX)/its
-dist_its_DATA = glade.loc glade1.its glade2.its gtkbuilder.its \
-gsettings.loc gsettings.its metainfo.loc metainfo.its
+
+ITS_FILES = \
+  glade1.its glade2.its gtkbuilder.its \
+  gsettings.its \
+  metainfo.its
+
+LOC_FILES = \
+  glade.loc \
+  gsettings.loc \
+  metainfo.loc
+
+dist_its_DATA = $(ITS_FILES) $(LOC_FILES)
+
+# Checks the XML files against their schemas.
+check-local:
+       @for file in $(ITS_FILES); do \
+         echo "Checking $$file..."; \
+         echo "$(XMLLINT) --noout --schema $(top_srcdir)/src/its.xsd $(srcdir)/$$file"; \
+         $(XMLLINT) --noout --schema $(top_srcdir)/src/its.xsd $(srcdir)/$$file || exit 1; \
+       done
+       @for file in $(LOC_FILES); do \
+         echo "Checking $$file..."; \
+         echo "$(XMLLINT) --noout --schema $(top_srcdir)/src/locating-rules.xsd $(srcdir)/$$file"; \
+         $(XMLLINT) --noout --schema $(top_srcdir)/src/locating-rules.xsd $(srcdir)/$$file || exit 1; \
+       done

diff --git a/gettext-tools/src/Makefile.am b/gettext-tools/src/Makefile.am
index 2cdedfb252e868b40e200177bc797b4ce59d2f01..d99da82aba77148cd7ab34873ade7438f044ea56 100644 (file)
--- a/gettext-tools/src/Makefile.am
+++ b/gettext-tools/src/Makefile.am
@@ -97,6 +97,7 @@ EXTRA_DIST += FILES project-id
 jardir = $(datadir)/gettext
 pkgdatadir = $(datadir)/gettext
 projectsdir = $(pkgdatadir)/projects
+schemadir = $(pkgdatadir)/schema
 pkglibdir = $(libdir)/gettext
 pkglibexecdir = $(libexecdir)/gettext
 
@@ -761,6 +762,14 @@ uninstall-tcl:
        $(RM) $(DESTDIR)$(pkgdatadir)/msgunfmt.tcl
 
 
+# Special rules for XML schemas.
+
+schema_DATA = \
+  its.xsd its-extensions.xsd \
+  locating-rules.xsd
+EXTRA_DIST += $(schema_DATA)
+
+
 # Support for relocatability.
 RELOCATABLE_LIBRARY_PATH = $(libdir)
 RELOCATABLE_SRC_DIR = $(top_srcdir)/gnulib-lib

diff --git a/gettext-tools/src/its-extensions.xsd b/gettext-tools/src/its-extensions.xsd
new file mode 100644 (file)
index 0000000..b85c3cb
--- /dev/null
+++ b/gettext-tools/src/its-extensions.xsd
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<schema targetNamespace="https://www.gnu.org/s/gettext/ns/its/extensions/1.0" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:gt="https://www.gnu.org/s/gettext/ns/its/extensions/1.0" elementFormDefault="qualified">
+
+  <annotation>
+    <documentation>XML schema extensions for *.its files, as understood by GNU gettext.
+
+Copyright (C) 2015-2024 Free Software Foundation, Inc.
+
+This file is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published
+by the Free Software Foundation, either version 3 of the License,
+or (at your option) any later version.
+
+This file is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see &lt;https://www.gnu.org/licenses/&gt;.
+
+Written by Bruno Haible &lt;bruno@clisp.org&gt;, 2024.
+</documentation>
+  </annotation>
+
+  <element name="preserveSpaceRule" type="gt:ExtendedPreserveSpaceRuleType"></element>
+  <element name="contextRule" type="gt:ContextRuleType"></element>
+  <element name="escapeRule" type="gt:EscapeRuleType"></element>
+
+  <complexType name="ExtendedPreserveSpaceRuleType">
+    <attribute name="selector" type="string" use="required"></attribute>
+    <attribute name="space" use="required">
+      <simpleType>
+        <restriction base="string">
+          <enumeration value="preserve"></enumeration>
+          <enumeration value="default"></enumeration>
+          <enumeration value="trim"></enumeration>
+          <enumeration value="paragraph"></enumeration>
+        </restriction>
+      </simpleType>
+    </attribute>
+  </complexType>
+
+  <complexType name="ContextRuleType">
+    <attribute name="selector" type="string" use="required"></attribute>
+    <attribute name="contextPointer" type="string" use="required"></attribute>
+    <attribute name="textPointer" type="string" use="optional"></attribute>
+  </complexType>
+
+  <complexType name="EscapeRuleType">
+    <attribute name="selector" type="string" use="required"></attribute>
+    <attribute name="escape" type="string" use="required"></attribute>
+  </complexType>
+</schema>

diff --git a/gettext-tools/src/its.xsd b/gettext-tools/src/its.xsd
new file mode 100644 (file)
index 0000000..a0bfe58
--- /dev/null
+++ b/gettext-tools/src/its.xsd
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<schema targetNamespace="http://www.w3.org/2005/11/its" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:its="http://www.w3.org/2005/11/its" xmlns:gt="https://www.gnu.org/s/gettext/ns/its/extensions/1.0" elementFormDefault="qualified">
+
+  <annotation>
+    <documentation>XML schema of *.its files, as understood by GNU gettext.
+
+Copyright (C) 2015-2024 Free Software Foundation, Inc.
+
+This file is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published
+by the Free Software Foundation, either version 3 of the License,
+or (at your option) any later version.
+
+This file is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see &lt;https://www.gnu.org/licenses/&gt;.
+
+Written by Bruno Haible &lt;bruno@clisp.org&gt;, 2024.
+</documentation>
+  </annotation>
+
+  <!-- Define elements and types in the gt namespace.  -->
+  <import namespace="https://www.gnu.org/s/gettext/ns/its/extensions/1.0" schemaLocation="its-extensions.xsd"/>
+
+  <element name="rules" type="its:RulesType"></element>
+
+  <complexType name="RulesType">
+    <sequence minOccurs="0" maxOccurs="unbounded">
+      <choice>
+        <element name="translateRule" type="its:TranslateRuleType">
+        </element>
+        <element name="locNoteRule" type="its:LocNoteRuleType">
+        </element>
+        <element name="withinTextRule" type="its:WithinTextRuleType">
+        </element>
+        <element name="preserveSpaceRule" type="its:PreserveSpaceRuleType">
+        </element>
+        <element ref="gt:preserveSpaceRule">
+        </element>
+        <element ref="gt:contextRule">
+        </element>
+        <element ref="gt:escapeRule">
+        </element>
+      </choice>
+    </sequence>
+    <attribute name="version" type="string" use="required" fixed="2.0"></attribute>
+  </complexType>
+
+  <complexType name="TranslateRuleType">
+    <attribute name="selector" type="string" use="required"></attribute>
+    <attribute name="translate" type="string" use="required"></attribute>
+  </complexType>
+
+  <complexType name="LocNoteRuleType">
+    <annotation>
+      <documentation>Note: An instance should not have both the 'locNotePointer' attribute and a 'locNote' child at the same time.
+</documentation></annotation>
+    <sequence minOccurs="0" maxOccurs="1">
+      <element name="locNote" type="string"></element>
+    </sequence>
+    <attribute name="selector" type="string" use="required"></attribute>
+    <attribute name="locNoteType" type="string" use="required"></attribute>
+    <attribute name="locNotePointer" type="string" use="optional"></attribute>
+    <!-- Valid in XML Schema 1.1 only:
+    <xsd:assert test="not(@locNotePointer and locNote)"/>
+    -->
+  </complexType>
+
+  <complexType name="WithinTextRuleType">
+    <attribute name="selector" type="string" use="required"></attribute>
+    <attribute name="withinText" type="string" use="required"></attribute>
+  </complexType>
+
+  <complexType name="PreserveSpaceRuleType">
+    <attribute name="selector" type="string" use="required"></attribute>
+    <attribute name="space" use="required">
+      <simpleType>
+        <restriction base="string">
+          <enumeration value="preserve"></enumeration>
+          <enumeration value="default"></enumeration>
+        </restriction>
+      </simpleType>
+    </attribute>
+  </complexType>
+</schema>

diff --git a/gettext-tools/src/locating-rules.xsd b/gettext-tools/src/locating-rules.xsd
new file mode 100644 (file)
index 0000000..3bb86fd
--- /dev/null
+++ b/gettext-tools/src/locating-rules.xsd
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
+  <xsd:annotation>
+    <xsd:documentation>XML schema of *.loc files, as understood by GNU gettext.
+
+Copyright (C) 2015-2024 Free Software Foundation, Inc.
+
+This file is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published
+by the Free Software Foundation, either version 3 of the License,
+or (at your option) any later version.
+
+This file is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see &lt;https://www.gnu.org/licenses/&gt;.
+
+Written by Bruno Haible &lt;bruno@clisp.org&gt;, 2024.
+</xsd:documentation></xsd:annotation>
+
+  <xsd:element name="locatingRules" type="LocatingRulesType">
+    <xsd:annotation>
+      <xsd:documentation></xsd:documentation>
+    </xsd:annotation>
+  </xsd:element>
+
+  <xsd:complexType name="LocatingRulesType">
+    <xsd:annotation>
+      <xsd:documentation>Example:
+&lt;locatingRules&gt;
+  &lt;locatingRule name=&quot;Glade&quot; pattern=&quot;*.glade&quot;&gt;
+  &lt;documentRule localName=&quot;GTK-Interface&quot; target=&quot;glade1.its&quot;/&gt;
+  &lt;documentRule localName=&quot;glade-interface&quot; target=&quot;glade2.its&quot;/&gt;
+  &lt;documentRule localName=&quot;interface&quot; target=&quot;gtkbuilder.its&quot;/&gt;
+  &lt;/locatingRule&gt;
+  &lt;locatingRule name=&quot;Glade&quot; pattern=&quot;*.glade2&quot;&gt;
+  &lt;documentRule localName=&quot;glade-interface&quot; target=&quot;glade2.its&quot;/&gt;
+  &lt;/locatingRule&gt;
+  &lt;locatingRule name=&quot;Glade&quot; pattern=&quot;*.ui&quot;&gt;
+  &lt;documentRule localName=&quot;interface&quot; target=&quot;gtkbuilder.its&quot;/&gt;
+  &lt;/locatingRule&gt;
+&lt;/locatingRules&gt;
+</xsd:documentation></xsd:annotation>
+    <xsd:sequence minOccurs="0" maxOccurs="unbounded">
+      <xsd:element name="locatingRule" type="LocatingRuleType">
+        <xsd:annotation>
+          <xsd:documentation></xsd:documentation>
+        </xsd:annotation></xsd:element>
+    </xsd:sequence>
+  </xsd:complexType>
+
+  <xsd:complexType name="LocatingRuleType">
+    <xsd:annotation>
+      <xsd:documentation>Example:
+&amp;lt;locatingRule name=&amp;quot;Glade&amp;quot; pattern=&amp;quot;*.glade&amp;quot;&amp;gt;
+  &amp;lt;documentRule localName=&amp;quot;GTK-Interface&amp;quot; target=&amp;quot;glade1.its&amp;quot;/&amp;gt;
+  &amp;lt;documentRule localName=&amp;quot;glade-interface&amp;quot; target=&amp;quot;glade2.its&amp;quot;/&amp;gt;
+  &amp;lt;documentRule localName=&amp;quot;interface&amp;quot; target=&amp;quot;gtkbuilder.its&amp;quot;/&amp;gt;
+&amp;lt;/locatingRule&amp;gt;
+
+Note: An instance should not have both the 'target' attribute and a 'documentRule' child at the same time.
+</xsd:documentation></xsd:annotation>
+    <xsd:sequence minOccurs="0" maxOccurs="unbounded">
+      <xsd:element name="documentRule" type="DocumentRuleType"></xsd:element>
+    </xsd:sequence>
+    <xsd:attribute name="pattern" type="xsd:string" use="required"></xsd:attribute>
+    <xsd:attribute name="name" type="xsd:string" use="optional"></xsd:attribute>
+    <xsd:attribute name="target" type="xsd:string" use="optional"></xsd:attribute>
+    <!-- Valid in XML Schema 1.1 only:
+    <xsd:assert test="not(@target and documentRule)"/>
+    -->
+  </xsd:complexType>
+
+  <xsd:complexType name="DocumentRuleType">
+    <xsd:annotation>
+      <xsd:documentation>Example:
+&lt;documentRule localName=&quot;GTK-Interface&quot; target=&quot;glade1.its&quot;/&gt;
+</xsd:documentation>
+    </xsd:annotation>
+    <xsd:attribute name="target" type="xsd:string" use="required"></xsd:attribute>
+    <xsd:attribute name="ns" type="xsd:string" use="optional"></xsd:attribute>
+    <xsd:attribute name="localName" type="xsd:string" use="optional"></xsd:attribute>
+  </xsd:complexType>
+</xsd:schema>