From: Bruno Haible Date: Sat, 5 Oct 2024 15:53:52 +0000 (+0200) Subject: doc: Document how to use custom *.its files. X-Git-Tag: v0.23~85 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=56d4d9e8cd2117063ce30ea2c73b4076d4488d2e;p=thirdparty%2Fgettext.git doc: Document how to use custom *.its files. Reported by Stefan Brüns at . * 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. --- diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi index aa5e15855..5de6bb7dd 100644 --- a/gettext-tools/doc/gettext.texi +++ b/gettext-tools/doc/gettext.texi @@ -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 diff --git a/gettext-tools/doc/msgfmt.texi b/gettext-tools/doc/msgfmt.texi index aa4d9055d..bced924a9 100644 --- a/gettext-tools/doc/msgfmt.texi +++ b/gettext-tools/doc/msgfmt.texi @@ -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 diff --git a/gettext-tools/doc/xgettext.texi b/gettext-tools/doc/xgettext.texi index a6037c11d..1aa983865 100644 --- a/gettext-tools/doc/xgettext.texi +++ b/gettext-tools/doc/xgettext.texi @@ -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}). diff --git a/gettext-tools/src/search-path.c b/gettext-tools/src/search-path.c index c12aeb09c..eed4f112d 100644 --- a/gettext-tools/src/search-path.c +++ b/gettext-tools/src/search-path.c @@ -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) {