doc/ping: Document decimal separator changes

Handling -i and -W parameter changed over the time, recently introducing
several *incompatible* changes:

* -i interval option
Until s20121114 ping used '.' (dot) as a decimal separator.

Then in 04d3f79 ("ping,ping6: Do not assume radix point is denoted by
'.' (-i option).") released in s20121121 decided to use decimal point
from locales (depended on $LC_NUMERIC). But even then it depend on
USE_IDN=yes which does not make much sense.

Recently d865d4c ("ping: Use C locale for parsing -i/-W without IDN")
addressed that and called setlocale() unconditionally. Maybe condition
based on ENABLE_NLS definition should have been discussed, but that
would probably lead just to LC_ALL=C setup in the scripts. People also
get confused by old behavior when decimal separator depends on locale
as some distros e.g. compile without IDN but other don't (see issue #273)
But that introduced *incompatible* behavior for next release, thus
documenting it in this commit.

562e0d5 fixed problems for -W, but also introduced yet another
*incompatible* behavior as invalid number is no longer fatal error (see
below).

d196177 ("ping: Add missing preprocesses checks around setlocale()
calls") unintentionally restored the old behavior, which was fixed by
previous commit 7a90bd5 ("ping: Fix handling decimal separator for -i/-W opt").

* -W timeout option
Until s20180629 there was undocumented behavior:

1) timeout silently rounded down to the next lower integral number
2) -W N for N < 1 was rounded to 0 => infinite timeout (obviously a bug)
3) -W Ns worked as expected (sleep for N sec, as 's' was dropped,
this could be considered as a feature)
4) -W Nm -W Nh also slept for N sec instead of N min or hour (obviously
a bug)

918e824 ("ping: add support for sub-second timeouts") released in
s20190324 fixed 1) and 2) by allowing real number with locale based
decimal separator when USE_IDN=yes configured. But that introduced
*incompatible* behavior as broke 3 and 4). As it was not documented in
release notes, people complained (issue #236).

562e0d5 ("ping: allow -i and -W option arguments contain garbage input")
restored 3) and 4) support (everything including and after first
non-numeric character is dropped, warning printed).

See also: #290

Signed-off-by: Petr Vorel <pvorel@suse.cz>

1 files changed, 7 insertions, 3 deletions

diff --git a/doc/ping.xml b/doc/ping.xml
index 3d0cff5..e1626ef 100644
--- a/doc/ping.xml
+++ b/doc/ping.xml
@@ -255,9 +255,11 @@ xml:id="man.ping">
         <listitem>
           <para>Wait
           <emphasis remap="I">interval</emphasis> seconds between
-          sending each packet. The default is to wait for one
-          second between each packet normally, or not to wait in
-          flood mode. Only super-user may set interval to values
+          sending each packet. Real number allowed with dot as
+          a decimal separator (regardless locale setup).
+          The default is to wait for one second between each packet
+          normally, or not to wait in flood mode.
+          Only super-user may set interval to values
           less than 0.2 seconds.</para>
         </listitem>
       </varlistentry>
@@ -682,6 +684,8 @@ xml:id="man.ping">
           affects only timeout in absence of any responses,
           otherwise
           <command>ping</command> waits for two RTTs.</para>
+          Real number allowed with dot as a decimal separator
+          (regardless locale setup).
         </listitem>
       </varlistentry>
     </variablelist>