Re: CVS commit: src/lib/libc/time

[Robert Elz <kre%munnari.OZ.AU@localhost>]

    Date:        Fri, 21 Oct 2022 15:00:41 -0400
    From:        Jan Schaumann <jschauma%netmeister.org@localhost>
    Message-ID:  <Y1LsWa/Kvy8eD+Qf%netmeister.org@localhost>

  | I believe that it's useful for people to know that
  | values outside the normal ranges are normalized,

Agreed.

  | as well as what that might look like.

The problem with trying to specify that, as we have
discovered, is that it is not easy.   The problem with
only doing half of the job here, is that sometime later
someone will read it, see what it says happens, and
what it doesn't say, and then expect the code to do
that - when it probably doesn't.

I'll come back to the rest of your message a bit lower,
but first a brief interlude ...

joerg%bec.de@localhost said:
  | I'd actually weasle out a bit

Yes, I would too, but

joerg%bec.de@localhost continued:
  | and just declare that normalisation is best effort and we
  | don't guarantee behavior for values that are very much outside
  | the range of the corresponding field. E.g. anything where
  | numerical overflow can happen in a component.

that isn't really the problem.  tzcode is very careful with arithmetic
to avoid those kinds of problems - if there's anywhere that it isn't
(which is still possible) that would be fixed if pointed out.

The problem is just the complexity of specifying what does happen,
in a way that fits the manual page in a way that is easier to
follow that simply reading the source (which isn't all that easy).

Now we return to the originally scheduelled e-mail:

jschauma%netmeister.org@localhost said:
  | That helps a lot when trying to determine _why_ the
  | output of mktime(3) [...]

  | Noting that values may cascade is useful [...]

I wonder if rather than attempting to specify what happens,
it might be better in this case to give examples of using
struct tm alterations, followed by mktime(), to alter the time,
and what the results are.

I'm not generally much in favour of examples in man pages,
I prefer specification, and leave it up to the reader to
determine how to use things to achieve the desired result,
as while giving an example or two (or three) of what can be
done is great for people who want to do one of those exact
things (and so can just copy the example) but is useless for
someone whose needs are different than any of the examples,
and is left trying to guess what will happen.

But here a two or three good examples of what happens might
just be a sane solution, perhaps two fairly simple ones, but
which demonstrate what happens with addition, and subtraction
- using just one field modification, but having that result in
a cascade through a few of the other fields - perhaps the 180
seconds forward, starting at 23:58 on the last day of some
month, and 32 hours backwards starting at 01:15 on the second
of a month.    Those should both produce entirely reasonable
and understandable results.

The third should show multiple modifications, in a way that produces,
or can do, a surprising result, perhaps 14 days forward, also
2 months forward, and some irrelevant small number of minutes backward
(that just to show that multiple fields can be altered, and they don't
need to all go in the same direction) starting at 13:27 on Dec 15 - where
the result can be Feb 29, or Mar 1 (at something a bit earlier than 13:27,
perhaps even make the number of minutes subtracted > 27 in that example)
depending upon whether the year is a leap year or not.   (Or make it
6 months forward (plus...) starting from August).  This one should be
one full example, with something like "if the starting year had been
NNNN then the result would have been...." added to show the difference
between leap years and others.

If this is done, the examples should all be tested to verify the
claimed results, but the man page should not need a lot of explanation
of why the result shown is achieved, just the input, the modification
made, and the result.

kre