Add documentation on the use of *printf() macros and libintl.

Backpatch to 8.1.X.

configure

@@ -13894,11 +13894,31 @@ fi
 # have all the features we need --- see below.
 
 if test "$PORTNAME" = "win32"; then
-  # Win32 gets this built unconditionally
+  # Win32 gets snprintf.c built unconditionally.
-  # libintl versions prior to 0.13 use the native *printf functions.
+  #
-  # Win32 *printf does not understand %$, so on Win32 using pre-0.13 libintl
+  # To properly translate all NLS languages strings, we must support the
-  # it is necessary to use the pg versions of *printf to properly process
+  # *printf() %$ format, which allows *printf() arguments to be selected
-  # NLS strings that use the %$ format.
+  # by position in the translated string.
+  #
+  # libintl versions < 0.13 use the native *printf() functions, and Win32
+  # *printf() doesn't understand %$, so we must use our /port versions,
+  # which do understand %$. libintl versions >= 0.13 include their own
+  # *printf versions on Win32.  The libintl 0.13 release note text is:
+  #
+  #   C format strings with positions, as they arise when a translator
+  #   needs to reorder a sentence, are now supported on all platforms.
+  #   On those few platforms (NetBSD and Woe32) for which the native
+  #   printf()/fprintf()/... functions don't support such format
+  #   strings, replacements are provided through <libintl.h>.
+  #
+  # We could use libintl >= 0.13's *printf() if we were sure that we had
+  # a litint >= 0.13 at runtime, but seeing that there is no clean way
+  # to guarantee that, it is best to just use our own, so we are sure to
+  # get %$ support. In include/port.h we disable the *printf() macros
+  # that might have been defined by libintl.
+  #
+  # We do this unconditionally whether NLS is used or not so we are sure
+  # that all Win32 libraries and binaries behave the same.
   pgac_need_repl_snprintf=yes
 else
   pgac_need_repl_snprintf=no
@@ -17158,9 +17178,12 @@ fi
 rm -f core *.core gmon.out bb.out conftest$ac_exeext conftest.$ac_objext conftest.$ac_ext
 fi
 
+# --------------------
+# Run tests below here
+# --------------------
 
 # Force use of our snprintf if system's doesn't do arg control
-# This feature is needed by NLS
+# See comment above at snprintf test for details.
 if test "$enable_nls" = yes -a "$pgac_need_repl_snprintf" = no; then
   echo "$as_me:$LINENO: checking whether printf supports argument control" >&5
 echo $ECHO_N "checking whether printf supports argument control... $ECHO_C" >&6

configure.in

@@ -1,5 +1,5 @@
 dnl Process this file with autoconf to produce a configure script.
-dnl $PostgreSQL: pgsql/configure.in,v 1.435 2005/12/06 04:53:02 momjian Exp $
+dnl $PostgreSQL: pgsql/configure.in,v 1.436 2005/12/06 18:35:09 momjian Exp $
 dnl
 dnl Developers, please strive to achieve this order:
 dnl
@@ -858,11 +858,31 @@ fi
 # have all the features we need --- see below.
 
 if test "$PORTNAME" = "win32"; then
-  # Win32 gets this built unconditionally
+  # Win32 gets snprintf.c built unconditionally.
-  # libintl versions prior to 0.13 use the native *printf functions.
+  #
-  # Win32 *printf does not understand %$, so on Win32 using pre-0.13 libintl
+  # To properly translate all NLS languages strings, we must support the
-  # it is necessary to use the pg versions of *printf to properly process
+  # *printf() %$ format, which allows *printf() arguments to be selected
-  # NLS strings that use the %$ format.
+  # by position in the translated string. 
+  # 
+  # libintl versions < 0.13 use the native *printf() functions, and Win32
+  # *printf() doesn't understand %$, so we must use our /port versions,
+  # which do understand %$. libintl versions >= 0.13 include their own
+  # *printf versions on Win32.  The libintl 0.13 release note text is:
+  #
+  #   C format strings with positions, as they arise when a translator
+  #   needs to reorder a sentence, are now supported on all platforms.
+  #   On those few platforms (NetBSD and Woe32) for which the native
+  #   printf()/fprintf()/... functions don't support such format
+  #   strings, replacements are provided through <libintl.h>.
+  #
+  # We could use libintl >= 0.13's *printf() if we were sure that we had
+  # a litint >= 0.13 at runtime, but seeing that there is no clean way
+  # to guarantee that, it is best to just use our own, so we are sure to
+  # get %$ support. In include/port.h we disable the *printf() macros
+  # that might have been defined by libintl.
+  #
+  # We do this unconditionally whether NLS is used or not so we are sure
+  # that all Win32 libraries and binaries behave the same.
   pgac_need_repl_snprintf=yes
 else
   pgac_need_repl_snprintf=no
@@ -1059,9 +1079,12 @@ AC_MSG_ERROR([[
 *** for the exact reason.]])],
 [AC_MSG_RESULT([cross-compiling])])
 
+# --------------------
+# Run tests below here
+# --------------------
 
 # Force use of our snprintf if system's doesn't do arg control
-# This feature is needed by NLS
+# See comment above at snprintf test for details.
 if test "$enable_nls" = yes -a "$pgac_need_repl_snprintf" = no; then
   PGAC_FUNC_PRINTF_ARG_CONTROL
   if test $pgac_cv_printf_arg_control != yes ; then

src/include/port.h

@@ -6,7 +6,7 @@
  * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/port.h,v 1.86 2005/12/06 05:13:46 tgl Exp $
+ * $PostgreSQL: pgsql/src/include/port.h,v 1.87 2005/12/06 18:35:10 momjian Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -115,8 +115,9 @@ extern unsigned char pg_tolower(unsigned char ch);
 #ifdef USE_REPL_SNPRINTF
 
 /*
- * Some versions of libintl try to replace printf and friends with macros;
+ * Versions of libintl >= 0.13 try to replace printf() and friends with
- * if we are doing likewise, make sure our versions win.
+ * macros to their own versions that understand the %$ format.  We do the
+ * same, so disable their macros, if they exist.
  */
 #ifdef vsnprintf
 #undef vsnprintf