prepare for 1.0.0 release and pkgs.janet inclusion

1 files changed, 24 insertions, 32 deletions

diff --git a/TECH.md b/TECH.md
index 6919db2..7c063d2 100644
--- a/TECH.md
+++ b/TECH.md
@@ -1,37 +1,29 @@
-# Time is a mess
-ISO C99 is fairly restrictive, while time in the wild is *wild*.
+# Reading Guide
+A general discussion on time, and why there isn't enough of it to discuss it.
 
-> The mktime function converts the broken-down time, expressed as local time, in the
-> structure pointed to by timeptr into a calendar time value with the same encoding as
-> that of the values returned by the time function. The original values of the tm_wday
-> and tm_yday components of the structure are ignored, and the original values of the
-> other components are not restricted to the ranges indicated above. On successful
-> completion, the values of the tm_wday and tm_yday components of the structure are
-> set appropriately, and the other components are set to represent the specified calendar
-> time, but with their values forced to the ranges indicated above; the final value of
-> tm_mday is not set until tm_mon and tm_year are determined.
+ISO C99 is fairly restrictive, intending to only really work with localtime.
+This assumption goes fairly deep, to the point of the macos libc (for example)
+presuming that all strftime calls are against localtime.
 
-This means that `mktime` must operate on `localtime` output.
-The implication (which is accurate) implies that `gmtime(t) == gmtime(mktime(localtime(t)))`.
+Thankfully, IANA tzcode is more reasonable, as it handles things correctly
+and provides timegm (which means you can operate in UTC until final display).
 
-As such, the source of truth is `time_t`, which is UTC-only.
-When we want to modify a `time_t`, we want to use localtime to perform the modification.
+On the overall, the package wraps around all ISO C99 functions that are not
+marked for future deprecation, plus timegm.
+The native wrapping is optimized for working primarily with time_t, only really
+using struct tm for final output and intermediate representations.
+This is how it's recommended to use the library as well.
 
-`strftime` actually can handle a `gmtime`, but various platforms are buggy.
-For example, macOS `%z %Z` will correctly report UTC but will report the localtime offset.
-On Linux, the same format will correctly report an offset of exactly `+0000`, but claim to be in `GMT`.
-As such, `%z` and `%Z` cannot be counted on.
+The primary thing missing is the ability to represent an arbitrary-timezone.
+For example, representing EST while localtime is CET.
+Unfortunately, ISO C99 simply does not provide a way of doing this.
+IANA tzcode does have ways to do this, namely via the NetBSD-inspired
+`_z`-terminated functions.
+Unfortunately, making those usable without completely messing up the codebase
+is non-trivial.
 
-Ok, `%z` and `%Z` don't work correctly because `struct tm` is often extended.
-When I convert to and from a dictionary, I lose that information.
-
-Ok I've confirmed that MacOS has bugs in the libc and have now reported them.
-
-I've pulled in eggert tz. This helps a lot, but some details are still unfortunate (due to the spec).
-The spec specifies quite explicitly that mktime operates on localtime output, which means I'll most
-likely have to wrap all time_t manipulations in a localtime.
-Let's start with the native api, and then the janet wrapper will purely speak time_t, I think?
-I technically also have automatic "free" access to non-ISOC99 things, since they're simply
-there to be used. However, I'd need to find a way to expose some libtz internals (as they can
-redefine time_t, define timezone_t, etc) to get that working.
-As such, I don't think I'll be doing that.
+Anyway, if nothing else, something really fun that came out of this project
+is that I got to report a libc bug to apple, so that's cool.
+It's been almost a month and they don't seem to have acknowledged it, so if you
+have to work with time, I would recommend just using IANA tzcode.
+It's literally standard.