From: Bruno Haible <bruno@clisp.org>
Date: Fri, 15 Aug 2008 09:58:46 +0000 (+0000)
Subject: For Python, recommend format strings with named arguments.
X-Git-Tag: v0.18~382
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=41ac5251a20f23e4be590498874265892d4ccfab;p=thirdparty%2Fgettext.git

For Python, recommend format strings with named arguments.
---

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index 3df94d5be..88b1f798c 100644
--- 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 39bedc4a5..8b82eb065 100644
--- 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