Update string parsing/formatting documentation

Expands "ISO Extensions" page in the docs into a more comprehensive overview of using strings in Temporal, including a new FAQ. Also renames the URL of that page to be more generic, and updates links to it.
tc39 · Feb 16, 2022 · 98f90c8 · 98f90c8
1 parent 3f2b758
commit 98f90c8
Show file tree

Hide file tree

Showing 11 changed files with 419 additions and 132 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -233,24 +233,21 @@ date.daysInYear; // => 365
 
 See [Temporal.Calendar Documentation](./calendar.md) for detailed documentation.
 
-## Object Relationship
+## Object relationship
 
 <img src="object-model.svg">
 
-## String Persistence
+## String persistence, parsing, and formatting
 
 All `Temporal` types have a string representation for persistence and interoperability.
-The correspondence between types and strings is shown below.
-For more information about extensions to the ISO 8601 / RFC 3339 standards that are used by Temporal and which are intended to be put on a standards track, see [ISO string extensions](./iso-string-ext.md).
+The correspondence between types and machine-readable strings is shown below.
+For more information about string parsing, serialization, and formatting in `Temporal` (including how Temporal is using industry standards like ISO 8601 and RFC 3339), see [String Parsing, Serialization, and Formatting](./strings.md).
 
 <img src="persistence-model.svg">
 
-## Other Documentation
-
-### **Key Concepts**
+## Other documentation
 
 - [Ambiguity](./ambiguity.md) &mdash; Explanation of missing times and double times due to daylight saving and time zone changes.
 - [Balancing](./balancing.md) &mdash; Explanation of when `Temporal.Duration` units wrap around to 0 and when they don't.
-- [ISO String Extensions](./iso-string-ext.md) &mdash; Discussion of extensions to the ISO 8601 and/or RFC 3339 standards which are used by `Temporal`.
 - [Why do Temporal instances have a Calendar?](./calendar-review.md) &mdash; Background about why types like `Temporal.PlainDate` or `Temporal.PlainDate` contain a calendar.
   These extensions are being actively worked on with IETF to get them on a standards track.
diff --git a/docs/iso-string-ext.md b/docs/iso-string-ext.md
diff --git a/docs/ja/README.md b/docs/ja/README.md
@@ -80,7 +80,7 @@ const zonedDateTime = Temporal.ZonedDateTime.from({
 }); // => 1995-12-07T03:24:30.0000035-08:00[America/Los_Angeles]
 ```
 
-これは Tempral において最も多くの情報を持つタイプであり、`Temporal.TimeZone`、`Temporal.Instant`、`Temporal.PlainDateTime`（これには `Temporal.Calendar` が含まれます）の組み合わせとしてみなせます。
+これは Temporal において最も多くの情報を持つタイプであり、`Temporal.TimeZone`、`Temporal.Instant`、`Temporal.PlainDateTime`（これには `Temporal.Calendar` が含まれます）の組み合わせとしてみなせます。
 
 より詳しくは[Temporal.ZonedDateTime Documentation](../zoneddatetime.md)を参照してください。
 
@@ -224,7 +224,7 @@ date.daysInYear; // => 365
 
 ## 文字列による永続性
 
-すべての`Temporal`タイプは、永続性や相互運用性のために文字列による表現を持っています。各タイプと文字列表現の対応を以下に示します。Temporal で使用されている ISO 8601 や RFC 3339 に関する、より詳細な情報と標準化に向けた取り組みに関しては[ECMAScript 拡張の ISO-8601 と RFC 3339](./iso-string-ext.md)を参照してください。
+すべての`Temporal`タイプは、永続性や相互運用性のために文字列による表現を持っています。各タイプと文字列表現の対応を以下に示します。Temporal で使用されている ISO 8601 や RFC 3339 に関する、より詳細な情報と標準化に向けた取り組みに関しては[ECMAScript 拡張の ISO-8601 と RFC 3339](./strings.md)を参照してください。
 
 <img src="../persistence-model.svg">
 
@@ -234,5 +234,4 @@ date.daysInYear; // => 365
 
 - [曖昧性](./ambiguity.md) &mdash; 時間に関する情報が欠落して曖昧さを引き起こす仕組み、2 つのタイプの時間オブジェクトが必要な理由、サマータイムやタイムゾーンの定義変更による影響
 - [バランシング](./balancing.md) &mdash; `Temporal.Duration`の単位が、いつ繰り上げされる（またはされない）のかについての説明
-- [ISO 文字列の拡張](./iso-string-ext.md) &mdash; `Temporal`で使用されている ISO 8601 および RFC 3339 の拡張に関する議論、IETF と連携した標準化への取り組み
 - [なぜ Temporal インスタンスはカレンダーの情報を持っているのか？](./calendar-review.md) &mdash; `Temporal.PlainDate`や`Temporal.PlainDate`がカレンダーシステムを保持している理由と背景
diff --git a/docs/persistence-model.svg b/docs/persistence-model.svg
diff --git a/docs/plaindate.md b/docs/plaindate.md
@@ -631,7 +631,7 @@ The string can be passed to `Temporal.PlainDate.from()` to create a new `Tempora
 
 Normally, a calendar annotation is shown when `date`'s calendar is not the ISO 8601 calendar.
 By setting the `calendarName` option to `'always'` or `'never'` this can be overridden to always or never show the annotation, respectively.
-For more information on the calendar annotation, see [ISO string extensions](./iso-string-ext.md#calendar-systems).
+For more information on the calendar annotation, see [the `Temporal` string formats documentation](./strings.md#calendar-systems).
 
 Example usage:
 

diff --git a/docs/plaindatetime.md b/docs/plaindatetime.md
@@ -875,7 +875,7 @@ Note that rounding may change the value of other units as well.
 
 Normally, a calendar annotation is shown when `datetime`'s calendar is not the ISO 8601 calendar.
 By setting the `calendarName` option to `'always'` or `'never'` this can be overridden to always or never show the annotation, respectively.
-For more information on the calendar annotation, see [ISO string extensions](./iso-string-ext.md#calendar-systems).
+For more information on the calendar annotation, see [the `Temporal` string formats documentation](./strings.md#calendar-systems).
 
 Example usage:
 

diff --git a/docs/plainmonthday.md b/docs/plainmonthday.md
@@ -257,7 +257,7 @@ The string can be passed to `Temporal.PlainMonthDay.from()` to create a new `Tem
 
 Normally, a calendar annotation is shown when `monthDay`'s calendar is not the ISO 8601 calendar.
 By setting the `calendarName` option to `'always'` or `'never'` this can be overridden to always or never show the annotation, respectively.
-For more information on the calendar annotation, see [ISO string extensions](./iso-string-ext.md#calendar-systems).
+For more information on the calendar annotation, see [the `Temporal` string formats documentation](./strings.md#calendar-systems).
 
 Example usage:
 

diff --git a/docs/plainyearmonth.md b/docs/plainyearmonth.md
@@ -517,7 +517,7 @@ The string can be passed to `Temporal.PlainYearMonth.from()` to create a new `Te
 
 Normally, a calendar annotation is shown when `yearMonth`'s calendar is not the ISO 8601 calendar.
 By setting the `calendarName` option to `'always'` or `'never'` this can be overridden to always or never show the annotation, respectively.
-For more information on the calendar annotation, see [ISO string extensions](./iso-string-ext.md#calendar-systems).
+For more information on the calendar annotation, see [the `Temporal` string formats documentation](./strings.md#calendar-systems).
 
 Example usage: