Re: Potentially misleading documentation of SECONDS variable

[bash]

On Wed, Aug 07, 2024 at 01:25:35AM +0900, Koichi Murase wrote:
> is supposed to imply that technically. It says "The number of seconds
> at shell invocation", so the starting time point is considered to have
> only the "second" resolution and doesn't have the subsecond
> resolution. Then, when a value is assigned, the starting time point
> would be updated to the number of "seconds" at the assignment.
> 
"seconds" being in quotes here since it is not actually the "number of
seconds" but rather "the time passed truncated to whole-second
resolution". :) 

> For example, when the assignment occurs at time X.7, the recorded time
> becomes just X (with the fraction part being truncated). Then, the
> value obtained from SECONDS is incremented when the clock becomes
> (X+1).0. This is consistent with the observed behavior.
> 
I agree! It's the truncating part that is the cause of this
confusion.

> However, I agree that this is implicit and ambiguous. A minimal
> modification is probably something like
> 
> diff --git a/doc/bash.1 b/doc/bash.1
> index 1f0a23d3..3ace21e9 100644
> --- a/doc/bash.1
> +++ b/doc/bash.1
> @@ -2091,7 +2091,7 @@ the value returned upon subsequent
>  references is
>  the number of seconds since the assignment plus the value assigned.
>  The number of seconds at shell invocation and the current time are always
> -determined by querying the system clock.
> +determined by querying the system clock at the resolution of a second.
>  If
>  .SM
>  .B SECONDS
> diff --git a/doc/bashref.texi b/doc/bashref.texi
> index 510b43f6..6ee0083b 100644
> --- a/doc/bashref.texi
> +++ b/doc/bashref.texi
> @@ -7038,7 +7038,7 @@ Assignment to this variable resets the count to
> the value assigned, and the
>  expanded value becomes the value assigned plus the number of seconds
>  since the assignment.
>  The number of seconds at shell invocation and the current time are always
> -determined by querying the system clock.
> +determined by querying the system clock at the resolution of a second.
>  If @env{SECONDS}
>  is unset, it loses its special properties,
>  even if it is subsequently reset.
>
Ideally, I would have it stating something about the possible
discrepancy due to truncating the underlaying, higher resolution value.
Maybe something like:
" +determined by querying the system clock, disregarding any subsecond
portion of the system clock value"
Such information would have helped me understand what is happening, at
least :)