Normative: Calendar and TimeZone removals

docs/README.md

@@ -31,7 +31,7 @@ A cookbook to help you get started and learn the ins and outs of Temporal is ava
 The Temporal API follows a convention of using types whose names start with "Plain" (like `Temporal.PlainDate`, `Temporal.PlainTime`, and `Temporal.PlainDateTime`) for objects which do not have an associated time zone.
 Converting between such types and exact time types (`Temporal.Instant` and `Temporal.ZonedDateTime`) can be ambiguous because of time zones and daylight saving time, and the Temporal API lets developers configure how this ambiguity is resolved.
 
-Several important concepts are explained elsewhere: [exact time, wall-clock time, time zones, DST, handling ambiguity, and more](./ambiguity.md).
+Several important concepts are explained elsewhere: [exact time, wall-clock time, time zones, DST, handling ambiguity, and more](./timezone.md).
 
 ### **Temporal.Now**
 
@@ -53,7 +53,7 @@ See [Temporal.Now Documentation](./now.md) for detailed documentation.
 ### **Temporal.Instant**
 
 A `Temporal.Instant` represents a fixed point in time (called **"exact time"**), without regard to calendar or location, e.g. July 20, 1969, at 20:17 UTC.
-For a human-readable local calendar date or clock time, use a `Temporal.TimeZone` and `Temporal.Calendar` to obtain a `Temporal.ZonedDateTime` or `Temporal.PlainDateTime`.
+For a human-readable local calendar date or clock time, use a time zone and calendar identifier to obtain a `Temporal.ZonedDateTime` or `Temporal.PlainDateTime`.
 
 ```js
 const instant = Temporal.Instant.from('1969-07-20T20:17Z');
@@ -83,7 +83,7 @@ const zonedDateTime = Temporal.ZonedDateTime.from({
 }); // => 1995-12-07T03:24:30.0000035-08:00[America/Los_Angeles]
 ```
 
-As the broadest `Temporal` type, `Temporal.ZonedDateTime` can be considered a combination of `Temporal.TimeZone`, `Temporal.Instant`, and `Temporal.PlainDateTime` (which includes `Temporal.Calendar`).
+As the broadest `Temporal` type, `Temporal.ZonedDateTime` can be considered a combination of `Temporal.Instant` and `Temporal.PlainDateTime` with a time zone identifier.
 
 See [Temporal.ZonedDateTime Documentation](./zoneddatetime.md) for detailed documentation.
 
@@ -126,7 +126,7 @@ See [Temporal.PlainTime Documentation](./plaintime.md) for detailed documentatio
 
 A `Temporal.PlainDateTime` represents a calendar date and wall-clock time that does not carry time zone information, e.g. December 7th, 1995 at 3:00 PM (in the Gregorian calendar).
 
-It can be converted to a `Temporal.ZonedDateTime` using a `Temporal.TimeZone`.
+It can be converted to a `Temporal.ZonedDateTime` using time zone identifier.
 For use cases that require a time zone, especially using arithmetic or other derived values, consider using `Temporal.ZonedDateTime` instead because that type automatically adjusts for Daylight Saving Time.
 
 ```js
@@ -192,43 +192,26 @@ Unlike the other Temporal types, the units in `Temporal.Duration` don't naturall
 
 See [Duration balancing](./balancing.md) for more on this topic.
 
-### **Temporal.TimeZone**
+### Time Zones
 
-A `Temporal.TimeZone` represents an IANA time zone, a specific UTC offset, or UTC itself.
-Time zones translate from a date/time in UTC to a local date/time.
-Because of this `Temporal.TimeZone` can be used to convert between `Temporal.Instant` and `Temporal.PlainDateTime` as well as finding out the offset at a specific `Temporal.Instant`.
+A time zone in ECMAScript is usually represented by an IANA Time Zone Database identifier such as `'America/Los_Angeles'`, `'Asia/Tokyo'`, or `'UTC'`.
+Fixed-offset time zone identifiers like `'+05:30'` may also be used, although this usage is discouraged because offsets for a particular location may change in response to political changes.
 
-It is also possible to implement your own time zones.
+Time zones translate between a date/time in UTC to a local calendar date and wall clock time.
+`Temporal.ZonedDateTime` provides built-in support for time-zone-aware applications.
+A time zone is required to convert from `Temporal.Instant` or `Temporal.PlainDateTime` to `Temporal.ZonedDateTime`.
 
-```js
-const timeZone = Temporal.TimeZone.from('Africa/Cairo');
-timeZone.getInstantFor('2000-01-01T00:00'); // => 1999-12-31T22:00:00Z
-timeZone.getPlainDateTimeFor('2000-01-01T00:00Z'); // => 2000-01-01T02:00:00
-timeZone.getPreviousTransition(Temporal.Now.instant()); // => 2014-09-25T21:00:00Z
-timeZone.getNextTransition(Temporal.Now.instant()); // => null
-```
+See [`Temporal.ZonedDateTime` Documentation](./zoneddatetime.md) for more information.
+A conceptual explanation of handling [time zones, DST, and ambiguity in Temporal](./timezone.md) is also available.
 
-See [Temporal.TimeZone Documentation](./timezone.md) for detailed documentation.
-A conceptual explanation of handling [time zones, DST, and ambiguity in Temporal](./ambiguity.md) is also available.
+### Calendars
 
-### **Temporal.Calendar**
-
-A `Temporal.Calendar` represents a calendar system.
+Temporal supports multiple calendar systems.
 Most code will use the ISO 8601 calendar, but other calendar systems are available.
 
-Dates have associated `Temporal.Calendar` objects, to perform calendar-related math.
-Under the hood, this math is done by methods on the calendars.
-
-It is also possible to implement your own calendars.
-
-```js
-const cal = Temporal.Calendar.from('iso8601');
-const date = cal.dateFromFields({ year: 1999, month: 12, day: 31 }, {});
-date.monthsInYear; // => 12
-date.daysInYear; // => 365
-```
+Dates have associated calendar IDs, to perform calendar-related math.
 
-See [Temporal.Calendar Documentation](./calendar.md) for detailed documentation.
+See [Calendars in Temporal](./calendars.md) for detailed documentation.
 
 ## Object relationship
 
@@ -244,7 +227,7 @@ For more information about string parsing, serialization, and formatting in `Tem
 
 ## Other documentation
 
-- [Ambiguity](./ambiguity.md) — Explanation of missing times and double times due to daylight saving and time zone changes.
+- [Time Zones and Resolving Ambiguity](./timezone.md) — Explanation of missing times and double times due to daylight saving and time zone changes.
 - [Balancing](./balancing.md) — Explanation of when `Temporal.Duration` units wrap around to 0 and when they don't.
 - [Why do Temporal instances have a Calendar?](./calendar-review.md) — Background about why types like `Temporal.PlainDate` or `Temporal.ZonedDateTime` contain a calendar.
   These extensions are being actively worked on with IETF to get them on a standards track.