From 1e7ee6a4ba3ee626d9fb99be4a35365bce74b0f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Rodr=C3=ADguez?=
 <2887858+deivid-rodriguez@users.noreply.github.com>
Date: Sun, 7 Sep 2025 17:41:59 +0200
Subject: [DOC] Improve format specification docs

One example to describe how `*` works actually prints a warning:

```
$ ruby -we "sprintf('%d', 20, 14)"
=> -e:1: warning: too many arguments for format string
```

I think it's better to not use examples that print warnings, so I
propose to merge `*` docs with "width" specifier docs, and only include
the "correct" example.

After I believe `*` is not an actual flag, but a special value that the
width specifier can take.

Mention `*` special value in initial summary as well.
---
 doc/format_specifications.rdoc | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/doc/format_specifications.rdoc b/doc/format_specifications.rdoc
index bdfdc24953..a2755256df 100644
--- a/doc/format_specifications.rdoc
+++ b/doc/format_specifications.rdoc
@@ -30,8 +30,9 @@ It consists of:
 
 - A leading percent character.
 - Zero or more _flags_ (each is a character).
-- An optional _width_ _specifier_ (an integer).
-- An optional _precision_ _specifier_ (a period followed by a non-negative integer).
+- An optional _width_ _specifier_ (an integer, or <tt>*</tt>).
+- An optional _precision_ _specifier_ (a period followed by a non-negative
+  integer, or <tt>*</tt>).
 - A _type_ _specifier_ (a character).
 
 Except for the leading percent character,
@@ -125,13 +126,6 @@ Left-pad with zeros instead of spaces:
   sprintf('%6d', 100)  # => "   100"
   sprintf('%06d', 100) # => "000100"
 
-=== <tt>'*'</tt> Flag
-
-Use the next argument as the field width:
-
-  sprintf('%d', 20, 14)  # => "20"
-  sprintf('%*d', 20, 14) # => "                  14"
-
 === <tt>'n$'</tt> Flag
 
 Format the (1-based) <tt>n</tt>th argument into this field:
@@ -152,6 +146,11 @@ of the formatted field:
   # Ignore if too small.
   sprintf('%1d', 100)   # => "100"
 
+If the width specifier is <tt>'*'</tt> instead of an integer, the actual minimum
+width is taken from the argument list:
+
+  sprintf('%*d', 20, 14) # => "                  14"
+
 == Precision Specifier
 
 A precision specifier is a decimal point followed by zero or more
@@ -194,6 +193,11 @@ the number of characters to write:
   sprintf('%s', Time.now)    # => "2022-05-04 11:59:16 -0400"
   sprintf('%.10s', Time.now) # => "2022-05-04"
 
+If the precision specifier is <tt>'*'</tt> instead of a non-negative integer,
+the actual precision is taken from the argument list:
+
+  sprintf('%.*d', 20, 1)    # => "00000000000000000001"
+
 == Type Specifier Details and Examples
 
 === Specifiers +a+ and +A+
-- 
cgit v1.2.3