]> git.ipfire.org Git - thirdparty/gettext.git/commitdiff
doc: Document how to use custom *.its files.
authorBruno Haible <bruno@clisp.org>
Sat, 5 Oct 2024 15:53:52 +0000 (17:53 +0200)
committerBruno Haible <bruno@clisp.org>
Sat, 5 Oct 2024 15:53:52 +0000 (17:53 +0200)
Reported by Stefan BrĂ¼ns <stefan.bruens@rwth-aachen.de>
at <https://savannah.gnu.org/bugs/?64026>.

* gettext-tools/src/search-path.c (get_search_path): Improve comments.
* gettext-tools/doc/xgettext.texi: New subsection "Options for XML input files".
Move the description of --its out of subsection "Output details".
* gettext-tools/doc/msgfmt.texi: Document GETTEXTDATADIRS.
* gettext-tools/doc/gettext.texi (Installers): Document the
PREFIX/share/gettext/its/ directory.

gettext-tools/doc/gettext.texi
gettext-tools/doc/msgfmt.texi
gettext-tools/doc/xgettext.texi
gettext-tools/src/search-path.c

index aa5e15855e4d55aed12be1658eebdf107a37eab8..5de6bb7dd71c20311df508a767106db8ef19df58 100644 (file)
@@ -9886,6 +9886,14 @@ may be set, prior to configuration, to limit the installed set.
 @code{LINGUAS} should then contain a space separated list of two-letter
 codes, stating which languages are allowed.
 
+GNU @code{gettext} uses *.its and *.loc files (@pxref{Preparing ITS Rules})
+from other packages, provided they are installed in
+@file{@var{prefix}/share/gettext/its/},
+where @code{@var{prefix}} is the value of the @code{--prefix} option
+passed to @code{gettext}'s @code{configure} script.
+So, this is the canonical location for installing *.its and *.loc files
+from other packages.
+
 @node Programming Languages
 @chapter Other Programming Languages
 
index aa4d9055d3cc1384ce8ca04f75a1f02a8b3fb0e4..bced924a9fb534f3382fde95291a6df3fbdd18a8 100644 (file)
@@ -276,6 +276,18 @@ variable.
 For either operation modes, the @samp{-o} and @samp{--template}
 options are mandatory.
 
+If your XML file is not of one of the types covered by the system-wide
+installed *.its files,
+you need a particular *.its file and a corresponding *.loc file
+(@pxref{Preparing ITS Rules}).
+Furthermore you need to store these files
+in a directory @file{@var{parent_dir}/its/}
+@vindex GETTEXTDATADIRS@r{, environment variable}
+and set the environment variable @code{GETTEXTDATADIRS} to include
+@code{@var{parent_dir}}.
+More generally, the value of @code{GETTEXTDATADIRS} should be
+a colon-separated list of directory names.
+
 @subsection Input file syntax
 
 @table @samp
index a6037c11d16ac5666b875d51c765dc035e1fe6d4..1aa98386584c4eab4c298b744975209933b2016f 100644 (file)
@@ -473,6 +473,40 @@ This implementation of @code{xgettext} is able to process a few awkward
 cases, like strings in preprocessor macros, ANSI concatenation of
 adjacent strings, and escaped end of lines for continued strings.
 
+@subsection Options for XML input files
+
+When some of the input files are XML files
+and they are not of one of the types covered
+by the system-wide installed *.its files,
+a *.its file is needed for each such file type,
+so that @code{xgettext} can handle them.
+There are two ways to specify such a file:
+
+@itemize @bullet
+@item
+@table @samp
+@item --its=@var{file}
+@opindex --its@r{, @code{xgettext} option}
+Use the ITS rules defined in @var{file}.
+@end table
+
+@item
+The environment variable @code{GETTEXTDATADIRS}.
+Together with the *.its file, you need a corresponding *.loc file
+(@pxref{Preparing ITS Rules}).
+Furthermore you need to store these files
+in a directory @file{@var{parent_dir}/its/}
+@vindex GETTEXTDATADIRS@r{, environment variable}
+and set the environment variable @code{GETTEXTDATADIRS} to include
+@code{@var{parent_dir}}.
+More generally, the value of @code{GETTEXTDATADIRS} should be
+a colon-separated list of directory names.
+@end itemize
+
+Note that when the option @code{--its} is specified,
+the system-wide installed *.its files are ignored
+and the environment variable @code{GETTEXTDATADIRS} has no effect either.
+
 @subsection Output details
 
 @c --no-escape and --escape omitted on purpose.  They are not useful.
@@ -534,11 +568,6 @@ obsolete messages.
 Write out a NeXTstep/GNUstep localized resource file in @code{.strings} syntax.
 Note that this file format doesn't support plural forms.
 
-@item --its=@var{file}
-@opindex --its@r{, @code{xgettext} option}
-Use ITS rules defined in @var{file}.
-Note that this is only effective with XML files.
-
 @item --itstool
 @opindex --itstool@r{, @code{xgettext} option}
 Write out comments recognized by itstool (@uref{http://itstool.org}).
index c12aeb09c574bdb250e5887055611b810dd087af..eed4f112dc4404c2349f5e93fff7c144e42f0cb6 100644 (file)
@@ -112,9 +112,14 @@ fill (const char *dir, size_t len, void *data)
    The order in the path is as follows:
 
    1. $GETTEXTDATADIR or GETTEXTDATADIR
+      (used by the test suite)
    2. $GETTEXTDATADIRS
+      (used by users who install their own *.its and *.loc files)
    3. $XDG_DATA_DIRS, where each element is suffixed with "gettext"
-   4. $GETTEXTDATADIR or GETTEXTDATADIR, suffixed with PACKAGE_SUFFIX  */
+      (this is where distributions install *.its and *.loc files from
+      other packages)
+   4. $GETTEXTDATADIR or GETTEXTDATADIR, suffixed with PACKAGE_SUFFIX
+      (this is where gettext's *.its and *.loc files are installed)  */
 char **
 get_search_path (const char *sub)
 {