printf.3: wfix

Improve description of %a format.

The description of the %a/%A specifiers in the printf(3) man page
could stand some improvement.  In particular, it is not clear from the
current document what base is used for the "p±d" part of the format.

It can be inferred from the nature of %a that the base should be a power
of two.  And it can be further inferred from the nature of hexadecimal
floating-point literals in C (as specified by C99 and later) that the
base must exactly be the number two, but it would be helpful for the
printf(3) man page to state this explicitly.  My first expectation when
reading the man page was that the exponent would be taken in base 16;
after experimentation my second thought was that it would be base
FLT_RADIX (which is 2 on IEEE 754 floating-point systems, but 16 on
S/390).  Only by going back to the standard [1] could I determine that
the exponent in p-notation must always be taken from a base of 2.

Link: [1] POSIX.1-2024 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/printf.html>
Cc: Jonathan Wakely <jwakely@redhat.com>
Signed-off-by: Ken Pizzini <ken@gnu.org>
Message-ID: <b932f13642502e063ef139d57b8f3c496023bf4a.1731707666.git.ken@gnu.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/man/man3/printf.3 b/man/man3/printf.3
index 7a96ec9c71b9b406362b46d4e540d52c73526ae7..2129e26dc67ab75e7a64a782586d22fab41db7a3 100644 (file)
--- a/man/man3/printf.3
+++ b/man/man3/printf.3
@@ -767,8 +767,11 @@ and otherwise is sufficiently large to distinguish values of type
 .IR double .
 The digit before the radix point is unspecified for nonnormalized
 numbers, and nonzero but otherwise unspecified for normalized numbers.
-The exponent always contains at least one
-digit; if the value is zero, the exponent is 0.
+The exponent,
+.IR d ,
+is the appropriate exponent of 2 expressed as a decimal integer;
+it always contains at least one digit;
+if the value is zero, the exponent is 0.
 .TP
 .B c
 If no