From: Bruno Haible <bruno@clisp.org>
Date: Tue, 10 Sep 2024 15:12:28 +0000 (+0200)
Subject: doc: Document the <inttypes.h> macros for translators.
X-Git-Tag: v0.23~140
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9809152f2679964e1a3ba519781e7839938b94b9;p=thirdparty%2Fgettext.git

doc: Document the <inttypes.h> macros for translators.

Reported by Mingye Wang <arthur200126@gmail.com>
at <https://savannah.gnu.org/bugs/?66195>.

* gettext-tools/doc/gettext.texi (c-format, objc-format): Mention the
<inttypes.h> macro placeholders.
---

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index d46282153..88891eccc 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -9742,10 +9742,9 @@ strings.
 
 C format strings are described in POSIX (IEEE P1003.1 2001), section
 XSH 3 fprintf(),
-@uref{http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html}.
-See also the fprintf() manual page,
-@uref{http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php},
-@uref{http://informatik.fh-wuerzburg.de/student/i510/man/printf.html}.
+@uref{https://pubs.opengroup.org/onlinepubs/9799919799/functions/fprintf.html}.
+See also the fprintf() manual page
+@uref{https://www.kernel.org/doc/man-pages/online/pages/man3/fprintf.3.html,,man fprintf}.
 
 Although format strings with positions that reorder arguments, such as
 
@@ -9767,6 +9766,19 @@ on this reordering ability: On the few platforms where @code{printf()},
 or @file{libintl.so} provides replacement functions, and GNU @code{<libintl.h>}
 activates these replacement functions automatically.
 
+@cindex @code{inttypes.h}
+C format strings can contain placeholders
+that reference macros defined in ISO C 99 @code{<inttypes.h>}.
+For example, @code{<PRId64>} references the macro @code{PRId64}.
+The value of such a macro is system-dependent,
+but programmers and translators do not need to know this value.
+ISO C 23 specifies system-independent format string elements,
+for example, @code{"%w64d"} instead of @code{"%" PRId64};
+however, as of 2024, these are not implemented across systems
+and therefore cannot be used portably.
+@c We need it implemented in glibc and in gcc and clang; <libintl.h> could
+@c then do the rest, with the help of gnulib's *printf functions.
+
 @cindex outdigits
 @cindex Arabic digits
 As a special feature for Farsi (Persian) and maybe Arabic, translators can
@@ -9789,6 +9801,10 @@ Objective C format strings are like C format strings.  They support an
 additional format directive: "%@@", which when executed consumes an argument
 of type @code{Object *}.
 
+@cindex @code{inttypes.h}
+Objective C format strings, like C format strings, can contain placeholders
+that reference macros defined in ISO C 99 @code{<inttypes.h>}.
+
 @node c++-format
 @subsection C++ Format Strings