Improve documentation of 'format' conversions

* src/editfns.c (Fformat): More accurate description of %g and
effects of the various flags on it.  More accurate description of
integer conversions.

* doc/lispref/strings.texi (Formatting Strings): More accurate
description of %g and effects of the various flags on it.  More
accurate description of integer conversions.  (Bug#25557)

2 files changed, 35 insertions, 21 deletions

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index d343bcf5eff..d5980f62bd4 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -893,17 +893,18 @@ Functions}).  Thus, strings are enclosed in @samp{"} characters, and
 @item %o
 @cindex integer to octal
 Replace the specification with the base-eight representation of an
-integer.
+unsigned integer.
 
 @item %d
-Replace the specification with the base-ten representation of an
+Replace the specification with the base-ten representation of a signed
 integer.
 
 @item %x
 @itemx %X
 @cindex integer to hexadecimal
 Replace the specification with the base-sixteen representation of an
-integer.  @samp{%x} uses lower case and @samp{%X} uses upper case.
+unsigned integer.  @samp{%x} uses lower case and @samp{%X} uses upper
+case.
 
 @item %c
 Replace the specification with the character which is the value given.
@@ -918,8 +919,9 @@ floating-point number.
 
 @item %g
 Replace the specification with notation for a floating-point number,
-using either exponential notation or decimal-point notation, whichever
-is shorter.
+using either exponential notation or decimal-point notation.  The
+exponential notation is used if the exponent would be less than -4 or
+greater than or equal to the precision (default: 6).
 
 @item %%
 Replace the specification with a single @samp{%}.  This format
@@ -1000,9 +1002,11 @@ both flags are used, @samp{+} takes precedence.
   The flag @samp{#} specifies an alternate form which depends on
 the format in use.  For @samp{%o}, it ensures that the result begins
 with a @samp{0}.  For @samp{%x} and @samp{%X}, it prefixes the result
-with @samp{0x} or @samp{0X}.  For @samp{%e}, @samp{%f}, and @samp{%g},
-the @samp{#} flag means include a decimal point even if the precision
-is zero.
+with @samp{0x} or @samp{0X}.  For @samp{%e} and @samp{%f}, the
+@samp{#} flag means include a decimal point even if the precision is
+zero.  For @samp{%g}, it always includes a decimal point, and also
+forces any trailing zeros after the decimal point to be left in place
+where they would otherwise be removed.
 
   The flag @samp{0} ensures that the padding consists of @samp{0}
 characters instead of spaces.  This flag is ignored for non-numerical
@@ -1033,10 +1037,14 @@ ignored.
   All the specification characters allow an optional @dfn{precision}
 before the character (after the width, if present).  The precision is
 a decimal-point @samp{.} followed by a digit-string.  For the
-floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the
-precision specifies how many decimal places to show; if zero, the
-decimal-point itself is also omitted.  For @samp{%s} and @samp{%S},
-the precision truncates the string to the given width, so @samp{%.3s}
+floating-point specifications (@samp{%e} and @samp{%f}), the
+precision specifies how many digits following the decimal point to
+show; if zero, the decimal-point itself is also omitted.  For
+@samp{%g}, the precision specifies how many significant digits to show
+(significant digits are the first digit before the decimal point and
+all the digits after it).  If the precision of %g is zero or
+unspecified, it is treated as 1.  For @samp{%s} and @samp{%S}, the
+precision truncates the string to the given width, so @samp{%.3s}
 shows only the first three characters of the representation for
 @var{object}.  For other specification characters, the effect of
 precision is what the local library functions of the @code{printf}
diff --git a/src/editfns.c b/src/editfns.c
index 395b3f3faed..18384a7d03a 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -3823,12 +3823,14 @@ The format control string may contain %-sequences meaning to substitute
 the next available argument:
 
 %s means print a string argument.  Actually, prints any object, with `princ'.
-%d means print as number in decimal (%o octal, %x hex).
+%d means print as signed number in decimal.
+%o means print as unsigned number in octal, %x as unsigned number in hex.
 %X is like %x, but uses upper case.
 %e means print a number in exponential notation.
 %f means print a number in decimal-point notation.
-%g means print a number in exponential notation
-  or decimal-point notation, whichever uses fewer characters.
+%g means print a number in exponential notation if the exponent would be
+   less than -4 or greater than or equal to the precision (default: 6);
+   otherwise it prints in decimal-point notation.
 %c means print a number as a single character.
 %S means print any object as an s-expression (using `prin1').
 
@@ -3851,8 +3853,10 @@ The - and 0 flags affect the width specifier, as described below.
 The # flag means to use an alternate display form for %o, %x, %X, %e,
 %f, and %g sequences: for %o, it ensures that the result begins with
 \"0\"; for %x and %X, it prefixes the result with \"0x\" or \"0X\";
-for %e, %f, and %g, it causes a decimal point to be included even if
-the precision is zero.
+for %e and %f, it causes a decimal point to be included even if the
+the precision is zero; for %g, it causes a decimal point to be
+included even if the the precision is zero, and also forces trailing
+zeros after the decimal point to be left in place.
 
 The width specifier supplies a lower limit for the length of the
 printed representation.  The padding, if any, normally goes on the
@@ -3861,10 +3865,12 @@ character is normally a space, but it is 0 if the 0 flag is present.
 The 0 flag is ignored if the - flag is present, or the format sequence
 is something other than %d, %e, %f, and %g.
 
-For %e, %f, and %g sequences, the number after the "." in the
-precision specifier says how many decimal places to show; if zero, the
-decimal point itself is omitted.  For %s and %S, the precision
-specifier truncates the string to the given width.
+For %e and %f sequences, the number after the "." in the precision
+specifier says how many decimal places to show; if zero, the decimal
+point itself is omitted.  For %g, the precision specifies how many
+significant digits to print; zero or omitted are treated as 1.
+For %s and %S, the precision specifier truncates the string to the
+given width.
 
 usage: (format STRING &rest OBJECTS)  */)
   (ptrdiff_t nargs, Lisp_Object *args)