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

Backpatch to 8.1.X.

1 files changed, 29 insertions, 6 deletions

diff --git a/configure b/configure
index c95d1f53fa2..98f40347046 100755
--- a/configure
+++ b/configure
@@ -13894,11 +13894,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
@@ -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