bug#71572: [PATCH] seconds-to-string-approximate

[Eli Zaretskii <eliz@gnu.org>]

> From: JD Smith <jdtsmith@gmail.com>
> Date: Sat, 30 Nov 2024 13:58:52 -0500
> Cc: Eli Zaretskii <eliz@gnu.org>,
>  Adam Porter <adam@alphapapa.net>,
>  jonas@bernoul.li,
>  Paul Eggert <eggert@cs.ucla.edu>
> 
> I was recently reminded of the need for a more capable seconds-to-string.  
> 
> Anyone have any additional comments on this proposed patch?  If not, I'd suggest someone with access
> merges.

A few minor nits below, and then we can install:

> --- a/doc/lispref/os.texi
> +++ b/doc/lispref/os.texi
> @@ -2155,6 +2155,12 @@ Time Calculations
>  structure.  For instance, the 120th day in 2004 is April 29th.
>  @end defun
>  
> +@defun seconds-to-string delay &optional readable abbrev precision
> +Return a string describing a given @var{delay} (in seconds).  Optional
> +arguments can be used to configure a human readable delay using various
> +formats.  For example, a delay of 9861.5 seconds with @var{readable} set
> +to the symbol @code{expanded} returns "2 hours 44 minutes".

The strings should be in @samp (and then you can drop the quotes).

> +** Time & Date
> +
> ++++
> +*** 'seconds-to-string' includes new arguments to produce human-readable
> +delay strings in a variety of formats, for example "6 months 3 weeks" or
> +"5m 52.5s".

This should have a heading line, which is a single complete sentence.

> +(defvar seconds-to-string-readable
> +  `(("Y" "year"   "years"   ,(round (* 60 60 24 365.2425)))
> +    ("M" "month"  "months"  ,(round (* 60 60 24 30.436875)))
> +    ("w" "week"   "weeks"   ,(* 60 60 24 7))
> +    ("d" "day"    "days"    ,(* 60 60 24))
> +    ("h" "hour"   "hours"   ,(* 60 60))
> +    ("m" "minute" "minutes" 60)
> +    ("s" "second" "seconds" 1))
> +  "Formatting used by the function `seconds-to-string' with READABLE set.")

Please exp.lain in more detail the format of this list's elements, so
that people could modify it more easily in the future.

> +(defun seconds-to-string (delay &optional readable abbrev precision)
> +  "Convert time interval DELAY (in seconds) to a short string.
                                                    ^^^^^^^^^^^^
Why "short"?

> +By default, the returned string has two decimal precision in the
> +smallest unit that is larger than DELAY from the variable
> +`seconds-to-string'.

I couldn't parse this sentence.  "Two decimal precision"? is that a
typo?

Thanks.