Explain why the number argument must be the last.

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index 36f6fe8301a2e7d2aa969c17cb3ec889d8429013..5b11039d43ae1652c4db97053c194cc0f34b3500 100644 (file)
--- a/gettext-tools/doc/ChangeLog
+++ b/gettext-tools/doc/ChangeLog
@@ -1,3 +1,9 @@
+2008-05-06  Bruno Haible  <bruno@clisp.org>
+
+       * gettext.texi (Plural forms): Explain why the number argument must be
+       the last.
+       Reported by Benjamin Geer <benjamin.geer@gmail.com>.
+
 2008-04-25  Bruno Haible  <bruno@clisp.org>
 
        * ISO_639: Remove Adangme. Update Belarusian, Scottish Gaelic,

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index d7dcce6619d98e95a3bcd7834c9501dee47983fd..f584b42df19da6816de206e8cb15251bce0277e0 100644 (file)
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -6025,6 +6025,33 @@ printf (ngettext ("One file removed", "%d files removed", n), n);
 This works because the @samp{printf} function discards excess arguments that
 are not consumed by the format string.
 
+If this function is meant to yield a format string that takes two or more
+arguments, you can not use it like this:
+
+@smallexample
+printf (ngettext ("%d file removed from directory %s",
+                  "%d files removed from directory %s",
+                  n, dir),
+        n);
+@end smallexample
+
+@noindent
+because in many languages the translators want to replace the @samp{%d}
+with an explicit word in the singular case, just like ``one'' in English,
+and C format strings cannot consume the second argument but skip the first
+argument.  Instead, you have to reorder the arguments so that @samp{n}
+comes last:
+
+@smallexample
+printf (ngettext ("%$2d file removed from directory %$1s",
+                  "%$2d files removed from directory %$1s",
+                  dir, n),
+        n);
+@end smallexample
+
+@noindent
+See @ref{c-format} for details about this argument reordering syntax.
+
 It is also possible to use this function when the strings don't contain a
 cardinal number: