For Python, recommend format strings with named arguments.

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index 3df94d5beddf592b0a261b8b845f75c49ec303f6..88b1f798cee3da5d5eac04dcd75ca1535d142d50 100644 (file)
--- a/gettext-tools/doc/ChangeLog
+++ b/gettext-tools/doc/ChangeLog
@@ -1,3 +1,9 @@
+2008-08-15  Bruno Haible  <bruno@clisp.org>
+
+       * gettext.texi (Python): Recommend format strings with named arguments.
+       Reported by Alexander Dupuy <alex.dupuy@mac.com>
+       in <http://savannah.gnu.org/bugs/?24025>.
+
 2008-06-18  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
        * msggrep.texi: Drop leading whitespace.

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 39bedc4a51d90c2fce917a66bc18a09595058d25..8b82eb0653887f20ff397f26e27d8eaf2aeaae6d 100644 (file)
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -9513,6 +9513,36 @@ fully portable
 
 An example is available in the @file{examples} directory: @code{hello-python}.
 
+A note about format strings: Python supports format strings with unnamed
+arguments, such as @code{'...%d...'}, and format strings with named arguments,
+such as @code{'...%(ident)d...'}.  The latter are preferable for
+internationalized programs, for two reasons:
+
+@itemize @bullet
+@item
+When a format string takes more than one argument, the translator can provide
+a translation that uses the arguments in a different order, if the format
+string uses named arguments.  For example, the translator can reformulate
+@smallexample
+"'%(volume)s' has only %(freespace)d bytes free."
+@end smallexample
+@noindent
+to
+@smallexample
+"Only %(freespace)d bytes free on '%(volume)s'."
+@end smallexample
+@noindent
+Additionally, the identifiers also provide some context to the translator.
+
+@item
+In the context of plural forms, the format string used for the singular form
+does not use the numeric argument in many languages.  Even in English, one
+prefers to write @code{"one hour"} instead of @code{"1 hour"}.  Omitting
+individual arguments from format strings like this is only possible with
+the named argument syntax.  (With unnamed arguments, Python -- unlike C --
+verifies that the format string uses all supplied arguments.)
+@end itemize
+
 @node Common Lisp, clisp C, Python, List of Programming Languages
 @subsection GNU clisp - Common Lisp
 @cindex Common Lisp