gettext-0.19.7gettext-0.19.7

1 files changed, 294 insertions, 22 deletions

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 507c622..8391073 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -79,7 +79,7 @@ This file provides documentation for GNU @code{gettext} utilities.
 It also serves as a reference for the free Translation Project.
 
 @copying
-Copyright (C) 1995-1998, 2001-2012 Free Software Foundation, Inc.
+Copyright (C) 1995-1998, 2001-2015 Free Software Foundation, Inc.
 
 This manual is free documentation.  It is dually licensed under the
 GNU FDL and the GNU GPL.  This means that you can redistribute this
@@ -439,6 +439,7 @@ Individual Programming Languages
 * GCC-source::                  GNU Compiler Collection sources
 * Lua::                         Lua
 * JavaScript::                  JavaScript
+* Vala::                        Vala
 
 sh - Shell Script
 
@@ -468,6 +469,8 @@ Internationalizable Data
 * RST::                         Resource String Table
 * Glade::                       Glade - GNOME user interface description
 * GSettings::                   GSettings - GNOME user configuration schema
+* AppData::                     AppData - freedesktop.org application description
+* Preparing ITS Rules::         Preparing Rules for XML Internationalization
 
 Concluding Remarks
 
@@ -2606,7 +2609,7 @@ with the following one:
 
 @{
   static const char *messages[] = @{
-    gettext_noop ("some very meaningful message",
+    gettext_noop ("some very meaningful message"),
     gettext_noop ("and another one")
   @};
   const char *string;
@@ -6221,7 +6224,11 @@ The following rules are known at this point.  The language with families
 are listed.  But this does not necessarily mean the information can be
 generalized for the whole family (as can be easily seen in the table
 below).@footnote{Additions are welcome.  Send appropriate information to
-@email{bug-gnu-gettext@@gnu.org} and @email{bug-glibc-manual@@gnu.org}.}
+@email{bug-gnu-gettext@@gnu.org} and @email{bug-glibc-manual@@gnu.org}.
+The Unicode CLDR Project (@uref{http://cldr.unicode.org}) provides a
+comprehensive set of plural forms in a different format.  The
+@code{msginit} program has preliminary support for the format so you can
+use it as a baseline (@pxref{msginit Invocation}).}
 
 @table @asis
 @item Only one form:
@@ -6241,6 +6248,8 @@ Languages with this property include:
 Japanese, @c   122.1 million speakers
 Vietnamese, @c  68.6 million speakers
 Korean @c       66.3 million speakers
+@item Tai-Kadai family
+Thai @c         20.4 million speakers
 @end table
 
 @item Two forms, singular used for one only
@@ -6278,6 +6287,8 @@ Finnish, @c      5.0 million speakers
 Estonian @c      1.0 million speakers
 @item Semitic family
 Hebrew @c        5.3 million speakers
+@item Austronesian family
+Bahasa Indonesian @c 23.2 million speakers
 @item Artificial
 Esperanto @c       2 million speakers
 @end table
@@ -6453,6 +6464,23 @@ Languages with this property include:
 @item Slavic family
 Slovenian @c   1.9 million speakers
 @end table
+
+@item Six forms, special cases for one, two, all numbers ending in 02, 03, @dots{} 10, all numbers ending in 11 @dots{} 99, and others
+The header entry would look like this:
+
+@smallexample
+Plural-Forms: nplurals=6; \
+    plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 \
+    : n%100>=11 ? 4 : 5;
+@end smallexample
+
+@noindent
+Languages with this property include:
+
+@table @asis
+@item Afroasiatic family
+Arabic @c    246.0 million speakers
+@end table
 @end table
 
 You might now ask, @code{ngettext} handles only numbers @var{n} of type
@@ -7690,11 +7718,10 @@ changes needed in each.
 So, here comes a list of files, each one followed by a description of
 all alterations it needs.  Many examples are taken out from the GNU
 @code{gettext} @value{VERSION} distribution itself, or from the GNU
-@code{hello} distribution (@uref{http://www.franken.de/users/gnu/ke/hello}
-or @uref{http://www.gnu.franken.de/ke/hello/})  You may indeed
-refer to the source code of the GNU @code{gettext} and GNU @code{hello}
-packages, as they are intended to be good examples for using GNU
-gettext functionality.
+@code{hello} distribution (@uref{http://www.gnu.org/software/hello}).
+You may indeed refer to the source code of the GNU @code{gettext} and
+GNU @code{hello} packages, as they are intended to be good examples for
+using GNU gettext functionality.
 
 @menu
 * po/POTFILES.in::              @file{POTFILES.in} in @file{po/}
@@ -8754,7 +8781,7 @@ adds to the @file{configure.ac} or @file{configure.in} a line of the
 form
 
 @example
-AM_GNU_GETTEXT_VERSION(@value{VERSION})
+AM_GNU_GETTEXT_VERSION(@value{ARCHIVE-VERSION})
 @end example
 
 @noindent
@@ -9041,6 +9068,7 @@ strings.
 * qt-format::                   Qt Format Strings
 * qt-plural-format::            Qt Plural Format Strings
 * kde-format::                  KDE Format Strings
+* kde-kuit-format::             KUIT Format Strings
 * boost-format::                Boost Format Strings
 * lua-format::                  Lua Format Strings
 * javascript-format::           JavaScript Format Strings
@@ -9127,11 +9155,10 @@ of the @samp{str} object.
 
 Python @code{%} format strings are described in
 @w{Python Library reference} /
-@w{2. Built-in Types, Exceptions and Functions} /
-@w{2.2. Built-in Types} /
-@w{2.2.6. Sequence Types} /
-@w{2.2.6.2. String Formatting Operations}.
-@uref{http://www.python.org/doc/2.2.1/lib/typesseq-strings.html}.
+@w{5. Built-in Types} /
+@w{5.6. Sequence Types} /
+@w{5.6.2. String Formatting Operations}.
+@uref{http://docs.python.org/2/library/stdtypes.html#string-formatting-operations}.
 
 Python brace format strings are described in @w{PEP 3101 -- Advanced
 String Formatting}, @uref{http://www.python.org/dev/peps/pep-3101/}.
@@ -9289,7 +9316,7 @@ Qt format strings are described in the documentation of the QObject::tr method
 @uref{file:/usr/lib/qt-4.3.0/doc/html/qobject.html}.
 In summary, the only allowed directive is @samp{%n}.
 
-@node kde-format, boost-format, qt-plural-format, Translators for other Languages
+@node kde-format, kde-kuit-format, qt-plural-format, Translators for other Languages
 @subsection KDE Format Strings
 
 KDE 4 format strings are defined as follows:
@@ -9297,7 +9324,19 @@ A directive consists of a @samp{%} followed by a non-zero decimal number.
 If a @samp{%n} occurs in a format strings, all of @samp{%1}, ..., @samp{%(n-1)}
 must occur as well, except possibly one of them.
 
-@node boost-format, lua-format, kde-format, Translators for other Languages
+@node kde-kuit-format, boost-format, kde-format, Translators for other Languages
+@subsection KUIT Format Strings
+
+KUIT (KDE User Interface Text) is compatible with KDE 4 format strings,
+while it also allows programmers to add semantic information to a format
+string, through XML markup tags.  For example, if the first format
+directive in a string is a filename, programmers could indicate that
+with a @samp{filename} tag, like @samp{<filename>%1</filename>}.
+
+KUIT format strings are described in
+@uref{http://api.kde.org/frameworks-api/frameworks5-apidocs/ki18n/html/prg_guide.html#kuit_markup}.
+
+@node boost-format, lua-format, kde-kuit-format, Translators for other Languages
 @subsection Boost Format Strings
 
 Boost format strings are described in the documentation of the
@@ -9434,6 +9473,7 @@ that language, and to combine the resulting files using @code{msgcat}.
 * GCC-source::                  GNU Compiler Collection sources
 * Lua::                         Lua
 * JavaScript::                  JavaScript
+* Vala::                        Vala
 @end menu
 
 @node C, sh, List of Programming Languages, List of Programming Languages
@@ -10649,7 +10689,9 @@ with a single-letter name.
 gawk 3.1 or newer
 
 @item File extension
-@code{awk}
+@code{awk}, @code{gawk}, @code{twjr}.
+The file extension @code{twjr} is used by TexiWeb Jr
+(@uref{https://github.com/arnoldrobbins/texiwebjr}).
 
 @item String syntax
 @code{"abc"}
@@ -11956,7 +11998,7 @@ On platforms without gettext, the functions are not available.
 ---
 @end table
 
-@node JavaScript,  , Lua, List of Programming Languages
+@node JavaScript, Vala, Lua, List of Programming Languages
 @subsection JavaScript
 
 @table @asis
@@ -12010,6 +12052,60 @@ On platforms without gettext, the functions are not available.
 ---
 @end table
 
+@node Vala,  , JavaScript, List of Programming Languages
+@subsection Vala
+
+@table @asis
+@item RPMs
+vala
+
+@item File extension
+@code{vala}
+
+@item String syntax
+@itemize @bullet
+
+@item @code{"abc"}
+
+@item @code{"""abc"""}
+
+@end itemize
+
+@item gettext shorthand
+@code{_("abc")}
+
+@item gettext/ngettext functions
+@code{gettext}, @code{dgettext}, @code{dcgettext}, @code{ngettext},
+@code{dngettext}, @code{dpgettext}, @code{dpgettext2}
+
+@item textdomain
+@code{textdomain} function, defined under the @code{Intl} namespace
+
+@item bindtextdomain
+@code{bindtextdomain} function, defined under the @code{Intl} namespace
+
+@item setlocale
+Programmer must call @code{Intl.setlocale (LocaleCategory.ALL, "")}
+
+@item Prerequisite
+---
+
+@item Use or emulate GNU gettext
+Use
+
+@item Extractor
+@code{xgettext}
+
+@item Formatting with positions
+Same as for the C language.
+
+@item Portability
+autoconf (gettext.m4) and #if ENABLE_NLS
+
+@item po-mode marking
+yes
+@end table
+
 @c This is the template for new languages.
 @ignore
 
@@ -12059,6 +12155,8 @@ using GNU gettext.
 * RST::                         Resource String Table
 * Glade::                       Glade - GNOME user interface description
 * GSettings::                   GSettings - GNOME user configuration schema
+* AppData::                     AppData - freedesktop.org application description
+* Preparing ITS Rules::  Preparing Rules for XML Internationalization
 @end menu
 
 @node POT, RST, List of Data Formats, List of Data Formats
@@ -12104,7 +12202,7 @@ glade, libglade, glade2, libglade2, intltool
 @code{xgettext}, @code{libglade-xgettext}, @code{xml-i18n-extract}, @code{intltool-extract}
 @end table
 
-@node GSettings,  , Glade, List of Data Formats
+@node GSettings, AppData, Glade, List of Data Formats
 @subsection GSettings - GNOME user configuration schema
 
 @table @asis
@@ -12118,6 +12216,180 @@ glib2
 @code{xgettext}, @code{intltool-extract}
 @end table
 
+@node AppData, Preparing ITS Rules, GSettings, List of Data Formats
+@subsection AppData - freedesktop.org application description
+
+@table @asis
+@item RPMs
+appdata-tools, appstream, libappstream-glib, libappstream-glib-builder
+
+@item File extension
+@code{appdata.xml}
+
+@item Extractor
+@code{xgettext}, @code{intltool-extract}, @code{itstool}
+@end table
+
+@menu
+@end menu
+
+@node Preparing ITS Rules,  , AppData, List of Data Formats
+@subsection Preparing Rules for XML Internationalization
+@cindex preparing rules for XML translation
+
+Marking translatable strings in an XML file is done through a separate
+"rule" file, making use of the Internationalization Tag Set standard
+(ITS, @uref{http://www.w3.org/TR/its20/}).  The currently supported ITS
+data categories are: @samp{Translate}, @samp{Localization Note},
+@samp{Elements Within Text}, and @samp{Preserve Space}.  In addition to
+them, @code{xgettext} also recognizes the following extended data
+categories:
+
+@table @samp
+@item Context
+
+This data category associates @code{msgctxt} to the extracted text.  In
+the global rule, the @code{contextRule} element contains the following:
+
+@itemize
+@item
+A required @code{selector} attribute.  It contains an absolute selector
+that selects the nodes to which this rule applies.
+
+@item
+A required @code{contextPointer} attribute that contains a relative
+selector pointing to a node that holds the @code{msgctxt} value.
+
+@item
+An optional @code{textPointer} attribute that contains a relative
+selector pointing to a node that holds the @code{msgid} value.
+@end itemize
+
+@item Escape Special Characters
+
+This data category indicates whether the special XML characters
+(@code{<}, @code{>}, @code{&}, @code{"}) are escaped with entity
+reference.  In the global rule, the @code{escapeRule} element contains
+the following:
+
+@itemize
+@item
+A required @code{selector} attribute.  It contains an absolute selector
+that selects the nodes to which this rule applies.
+
+@item
+A required @code{escape} attribute with the value @code{yes} or @code{no}.
+@end itemize
+
+@item Extended Preserve Space
+
+This data category extends the standard @samp{Preserve Space} data
+category with the additional value @samp{trim}.  The value means to
+remove the leading and trailing whitespaces of the content, but not to
+normalize whitespaces in the middle.  In the global rule, the
+@code{preserveSpaceRule} element contains the following:
+
+@itemize
+@item
+A required @code{selector} attribute.  It contains an absolute selector
+that selects the nodes to which this rule applies.
+
+@item
+A required @code{space} attribute with the value @code{default},
+@code{preserve}, or @code{trim}.
+@end itemize
+
+@end table
+
+All those extended data categories can only be expressed with global
+rules, and the rule elements have to have the
+@code{https://www.gnu.org/s/gettext/ns/its/extensions/1.0} namespace.
+
+Given the following XML document in a file @file{messages.xml}:
+
+@example
+<?xml version="1.0"?>
+<messages>
+  <message>
+    <p>A translatable string</p>
+  </message>
+  <message>
+    <p translatable="no">A non-translatable string</p>
+  </message>
+</messages>
+@end example
+
+To extract the first text content ("A translatable string"), but not the
+second ("A non-translatable string"), the following ITS rules can be used:
+
+@example
+<?xml version="1.0"?>
+<its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0">
+  <its:translateRule selector="/messages" translate="no"/>
+  <its:translateRule selector="//message/p" translate="yes"/>
+
+  <!-- If 'p' has an attribute 'translatable' with the value 'no', then
+       the content is not translatable.  -->
+  <its:translateRule selector="//message/p[@@translatable = 'no']"
+    translate="no"/>
+</its:rules>
+@end example
+
+@samp{xgettext} needs another file called "locating rule" 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:
+
+@example
+<?xml version="1.0"?>
+<locatingRules>
+  <locatingRule name="Messages" pattern="*.xml">
+    <documentRule localName="messages" target="messages.its"/>
+  </locatingRule>
+  <locatingRule name="Messages" pattern="*.msg" target="messages.its"/>
+</locatingRules>
+@end example
+
+The @code{locatingRule} element must have a @code{pattern} attribute,
+which denotes either a literal file name or a wildcard pattern of the
+XML file.  The @code{locatingRule} element can have child
+@code{documentRule} element, which adds checks on the content of the XML
+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
+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
+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
+@file{$prefix/share/gettext/its} directory.  Once those files are
+properly installed, @code{xgettext} can extract translatable strings
+from the matching XML files.
+
+@subsubsection Two Use-cases of Translated Strings in XML
+
+For XML, there are two use-cases of translated strings.  One is the case
+where the translated strings are directly consumed by programs, and the
+other is the case where the translated strings are merged back to the
+original XML document.  In the former case, special characters in the
+extracted strings shouldn't be escaped, while they should in the latter
+case.  To control wheter to escape special characters, the @samp{Escape
+Special Characters} data category can be used.
+
+To merge the translations, the @samp{msgfmt} program can be used with
+the option @code{--xml}.  @xref{msgfmt Invocation}, for more details
+about how one calls the @samp{msgfmt} program.  @samp{msgfmt}'s
+@code{--xml} option doesn't perform character escaping, so translated
+strings can have arbitrary XML constructs, such as elements for markup.
+
 @c This is the template for new data formats.
 @ignore
 
@@ -12369,19 +12641,19 @@ A copy of the license is included in @ref{GNU GPL}.
 @end menu
 
 @page
-@node GNU GPL
+@node GNU GPL, GNU LGPL, Licenses, Licenses
 @appendixsec GNU GENERAL PUBLIC LICENSE
 @cindex GPL, GNU General Public License
 @cindex License, GNU GPL
 @include gpl.texi
 @page
-@node GNU LGPL
+@node GNU LGPL, GNU FDL, GNU GPL, Licenses
 @appendixsec GNU LESSER GENERAL PUBLIC LICENSE
 @cindex LGPL, GNU Lesser General Public License
 @cindex License, GNU LGPL
 @include lgpl.texi
 @page
-@node GNU FDL
+@node GNU FDL,  , GNU LGPL, Licenses
 @appendixsec GNU Free Documentation License
 @cindex FDL, GNU Free Documentation License
 @cindex License, GNU FDL