Add an introduction to typical date time handling and issues

[darrenldl]

From issue #25

[darrenldl]

@gasche I've added an introduction section to the top of API doc, if you happen to have time to take a look.

[gasche]

Yes, I had a look at this, and I find it very nice, thanks! I think this issue can be closed.

It's a minor detail but I still find the presentation of tz_info in the Date_time documentation a bit confusing, because it is not clear (to me) that the "offset" is only used for ambiguous local datetimes, not in general. It still reads to me as if I was, more or less, asked (optionally) to say "Europe/Paris but always UTC+1 please".

(I wonder if it would be possible to put the documentation for t, which is more general, before the documentation for tz_info which is a more specialized type (possibly by declaring them as type t = ... and tz_info = ... ?), so that the documentation would flow better.)

[darrenldl]

Yep my apologies - I recall you raising the issue over at #25 but I haven't gotten to it yet.

I've changed the ordering of the type as you suggested (type t = ... and tz_info = ...), and have amended the section for tz_info to read

"
Time zone information of date time.

tz is the time zone tied. This is always defined even if only an offset provided during construction - if say only offset of 10 hours is provided, tz becomes "UTC+10".

offset is the offset from UTC, and provides an unambiguous specification of which timestamp/point the date time maps to on the UTC timeline. offset is defined if an offset is provided during construction via make_unambiguous or if an unambiguous offset can be deduced during construction via make.

In other words, offset is None exactly when it is not possible to assign an offset, and Some _ otherwise.
"

Hope that clarifies things, and specifically implies it is always used as much as possible.