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

Backpatch to 8.1.X.

diff --git a/configure b/configure
index 2fdc17b1cbf4d7618a817742e21de0089c958f4b..d6cd831c8d559dc9d091c319556afedfdcd97c23 100755 (executable)
--- a/configure
+++ b/configure
@@ -13853,11 +13853,31 @@ fi
 # have all the features we need --- see below.
 
 if test "$PORTNAME" = "win32"; then
-  # Win32 gets this 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
-  # it is necessary to use the pg versions of *printf to properly process
-  # NLS strings that use the %$ format.
+  # Win32 gets snprintf.c built unconditionally.
+  #
+  # To properly translate all NLS languages strings, we must support the
+  # *printf() %$ format, which allows *printf() arguments to be selected
+  # 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
@@ -17117,9 +17137,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

diff --git a/configure.in b/configure.in
index e01a257cea1b4d64984490b84c659e7ae0e0b024..67646da8e6f8e4cf58fb73cd1f1e9ea148f7b08d 100644 (file)
--- a/configure.in
+++ b/configure.in
@@ -851,11 +851,31 @@ fi
 # have all the features we need --- see below.
 
 if test "$PORTNAME" = "win32"; then
-  # Win32 gets this 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
-  # it is necessary to use the pg versions of *printf to properly process
-  # NLS strings that use the %$ format.
+  # Win32 gets snprintf.c built unconditionally.
+  #
+  # To properly translate all NLS languages strings, we must support the
+  # *printf() %$ format, which allows *printf() arguments to be selected
+  # 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
@@ -1052,9 +1072,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

diff --git a/src/include/port.h b/src/include/port.h
index 509518ac4da252dd01294f7ed7c09a52ff84cd4c..cb2d99fb04f94c32927c4c0e15167517ef9f60bb 100644 (file)
--- a/src/include/port.h
+++ b/src/include/port.h
@@ -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;
- * if we are doing likewise, make sure our versions win.
+ * Versions of libintl >= 0.13 try to replace printf() and friends with
+ * macros to their own versions that understand the %$ format.  We do the
+ * same, so disable their macros, if they exist.
  */
 #ifdef vsnprintf
 #undef vsnprintf