CLDR-16866 Add algorithm for first day of week. (#3303)

* CLDR-16866 Add algorithm for first day of week.

* CLDR-16866 formatting tweaks

* CLDR-16866 Add examples

* CLDR-16866 Fix iso example

docs/ldml/tr35-dates.md

@@ -1160,6 +1160,30 @@ Each `weekOfPreference` element provides, for its specified locales, an ordered
 | weekOfDate     | the week of April 11, 2016        | \<field type="week"\>\<relativePeriod>the week of {0}\<…        | The date pattern that replaces {0} is determined separately and may use the first day or workday of the week, the range of the full week or work week, etc.   |
 | weekOfInterval | the week of April 11–15           | \<field type="week"\>\<relativePeriod>the week of {0}\<…    |  (same comment as above) |
 
+#### First Day Overrides
+
+The calculation of the first day of the week depends on various fields in a locale_identifier, according to the following algorithm. The data in the `firstDay` elements is treated as a map from region to day, with any missing value using the value for 001.
+
+1. If there is a valid `-u-fw-` day value, return that day.
+2. Else if there is a valid `-u-rg-` region value, return that region's firstDay map value.
+3. Else if there is a valid `-u-ca-` calendar value, where that calendar specifies the first day, then return that first day. (Most calendars do not specify the first day.)
+4. Else if there is an explicit region subtag, then return that region's firstDay map value.
+5. Else if there is a valid `-u-sd-` subdivision value, return that region's firstDay map value.
+6. Else if the [Add Likely Subtags](tr35.html#Likely_Subtags) algorithm produces a region, return that region's firstDay map value.
+7. Else return the firstDay map value for 001.
+
+*Example:*
+
+| Locale Identifier | "Winning" subtags | Region |
+|----|----|----|
+|en-AU-u-ca-iso8601-fw-tue-rg-afzzzz-sd-cabc | -fw-tue | n/a, uses Tuesday |
+|en-AU-u-ca-iso8601-rg-afzzzz-sd-cabc | -rg-afzzzz | AF |
+|en-AU-u-ca-iso8601-sd-cabc | -ca-iso8601 | n/a, uses Monday |
+|en-AU-u-sd-cabc | -AU | AU |
+|en-u-sd-cabc | -sd-cabc | CA |
+|en | | US (from likely subtags) |
+|zxx | 001 | (fallback) |
+
 ### <a name="Time_Data" href="#Time_Data">Time Data</a>
 
 ```xml

docs/ldml/tr35.md

@@ -721,6 +721,7 @@ The BCP 47 form for keys and types is the canonical form, and recommended. Other
         in bcp47/<a href="https://github.com/unicode-org/cldr/blob/main/common/bcp47/calendar.xml" target="_blank">calendar.xml</a></b>.<br>
         This selects calendar-specific data within a locale used for formatting and parsing, such as date/time symbols and patterns; it also selects supplemental
         calendarData used for calendrical calculations.
+		The value can affect the computation of the first day of the week: see <a href='tr35-dates.md#first_day_overrides'>First Day Overrides</a>.
         </td></tr>
 <tr><td rowspan="10">"ca"<br>(calendar)</td>
     <td rowspan="10">Calendar algorithm<br><br><i>(For information on the calendar algorithms associated with the data used with these, see [<a href="#Calendars">Calendars</a>].)</i></td>
@@ -799,8 +800,10 @@ The BCP 47 form for keys and types is the canonical form, and recommended. Other
 
 <tr><td colspan="4"><b>A <a name="UnicodeFirstDayIdentifier" id="UnicodeFirstDayIdentifier" href="#UnicodeFirstDayIdentifier">Unicode First Day Identifier</a>
         defines the preferred first day of the week for calendar display. Specifying "fw" in a locale identifier overrides the default value specified by supplemental
-        week data for the region (see Part 4 Dates, <a href="tr35-dates.md#Week_Data">Week Data</a>). The valid values are those <i>name</i> attribute values in the <i>type</i> elements
-        of key name="fw" in bcp47/<a href="https://github.com/unicode-org/cldr/blob/main/common/bcp47/calendar.xml" target="_blank">calendar.xml</a></b>.
+        week data for the region (see Part 4 Dates, <a href="tr35-dates.md#Week_Data">Week Data</a>).
+		The valid values are those <i>name</i> attribute values in the <i>type</i> elements
+        of key name="fw" in bcp47/<a href="https://github.com/unicode-org/cldr/blob/main/common/bcp47/calendar.xml" target="_blank">calendar.xml</a>.
+		The value can affect the computation of the first day of the week: see <a href='tr35-dates.md#first_day_overrides'>First Day Overrides</a>.
         </td></tr>
 <tr><td rowspan="4">"fw"</td>
     <td rowspan="4">First day of week</td>
@@ -914,6 +917,7 @@ The BCP 47 form for keys and types is the canonical form, and recommended. Other
 <tr><td rowspan="2">"rg"</td>
     <td rowspan="2">Region Override</td><td>"uszzzz"<br><br></td><td rowspan="2">The value is a <a href="#unicode_subdivision_id">unicode_subdivision_id</a> of type “unknown” or “regular”; this consists of a <a href="#unicode_region_subtag">unicode_region_subtag</a> for a regular region (not a macroregion), suffixed either by “zzzz” (case is not significant) to designate the region as a whole, or by a unicode_subdivision_suffix to provide more specificity. For example, “en-GB-u-rg-uszzzz” represents a locale for British English but with region-specific defaults set to US for items such as default currency, default calendar and week data, default time cycle, and default measurement system and unit preferences.
 	The determination of preferred units depends on the locale identifer: the keys ms, mu, rg, the base locale (language, script, region) and the user preferences.
+	The value can affect the computation of the first day of the week: see <a href='tr35-dates.md#first_day_overrides'>First Day Overrides</a>.
 <i>For information about preferred units and unit conversion, see <a href="tr35-info.md#Unit_Conversion">Unit Conversion</a> and <a href="tr35-info.md#Unit_Preferences">Unit Preferences</a>.</i>
 	</td></tr>
         <tr><td>…</td></tr>
@@ -922,7 +926,9 @@ The BCP 47 form for keys and types is the canonical form, and recommended. Other
 <tr><td rowspan="2">"sd"</td>
     <td rowspan="2">Regional Subdivision</td>
             <td>"gbsct"</td>
-            <td rowspan="2">A <a href="#unicode_subdivision_id">unicode_subdivision_id</a>, which is a <a href="#unicode_region_subtag">unicode_region_subtag</a> concatenated with a unicode_subdivision_suffix.<br>For example, <i>gbsct</i> is “gb”+“sct” (where sct represents the subdivision code for Scotland). Thus “en-GB-u-sd-gbsct” represents the language variant “English as used in Scotland”. And both “en-u-sd-usca” and “en-US-u-sd-usca” represent “English as used in California”. See <b><i><a href="#Unicode_Subdivision_Codes">3.6.5 Subdivision Codes</a></i></b>.</td></tr>
+            <td rowspan="2">A <a href="#unicode_subdivision_id">unicode_subdivision_id</a>, which is a <a href="#unicode_region_subtag">unicode_region_subtag</a> concatenated with a unicode_subdivision_suffix.<br>For example, <i>gbsct</i> is “gb”+“sct” (where sct represents the subdivision code for Scotland). Thus “en-GB-u-sd-gbsct” represents the language variant “English as used in Scotland”. And both “en-u-sd-usca” and “en-US-u-sd-usca” represent “English as used in California”. See <b><i><a href="#Unicode_Subdivision_Codes">3.6.5 Subdivision Codes</a></i></b>.
+			The value can affect the computation of the first day of the week: see <a href='tr35-dates.md#first_day_overrides'>First Day Overrides</a>.
+		</td></tr>
         <tr><td>…</td></tr>
 
 <tr><td colspan="4"><b>A <a name="UnicodeSentenceBreakSuppressionsIdentifier" id="UnicodeSentenceBreakSuppressionsIdentifier" href="#UnicodeSentenceBreakSuppressionsIdentifier">Unicode Sentence Break Suppressions Identifier</a> defines a set of data to be used for suppressing certain sentence breaks that would otherwise be found by UAX #14 rules. The valid values are those <i>name</i> attribute values in the <i>type</i> elements of key name="ss" in bcp47/<a href="https://github.com/unicode-org/cldr/blob/main/common/bcp47/segmentation.xml" target="_blank">segmentation.xml</a></b>.</td></tr>