diff --git a/spec/errors.md b/spec/errors.md index bf20700799..21c5e536e9 100644 --- a/spec/errors.md +++ b/spec/errors.md @@ -347,13 +347,13 @@ for that specific _function_. #### Bad Option A **_Bad Option_** error is an error that occurs when there is -an implementation-defined error with an _option_ or its value. +an implementation-defined error with an _option_ or an _option value_. These might include: - A required _option_ is missing. - Mutually exclusive _options_ are supplied. -- An _option_ value provided to a _function_ during _function resolution_ +- An _option value_ provided to a _function_ during _function resolution_ does not match one of the implementation-defined types or values for that _function_; - or in which the literal _option_ value does not have the required format + or in which the _string value_ of an _option_ does not have the required format and thus cannot be processed into one of the expected implementation-defined types for that specific _function_. @@ -386,5 +386,5 @@ does not match the expected implementation-defined format. #### Unsupported Operation A **_Unsupported Operation_** error is an implementation-specific error -that occurs when a given _option_, _option_ value, _operand_ value, or some combination +that occurs when a given _option_, _option value_, _operand_, or some combination of these are incompatible or not supported by a given _function_ or its _function handler_. diff --git a/spec/formatting.md b/spec/formatting.md index 0f7cc641a5..6d1b1746a5 100644 --- a/spec/formatting.md +++ b/spec/formatting.md @@ -137,17 +137,12 @@ as well as a flag to indicate whether its formatted representation requires isolation from the surrounding text. -For each _option_ value, the _resolved value_ MUST indicate if the value +For each _option value_, the _resolved value_ MUST indicate if the value was directly set with a _literal_, as opposed to being resolved from a _variable_. This is to allow _functions handlers_ to require specific _options_ to be set using _literals_. > For example, the _default functions_ `:number` and `:integer` require that the _option_ -> `select` be set with a _literal_ (`plural`, `ordinal`, or `exact`). -> Allowing a _variable_ in this _option_ would produce a _message_ that -> is impossible to translate because the set of _keys_ is tied to the _selector_ chosen. - -> [!NOTE] -> Such information is irrelevant for _resolved values_ not used as the value of an _option_. +> `select` be set with a _literal_ _option value_ (`plural`, `ordinal`, or `exact`). The form that _resolved values_ take is implementation-dependent, and different implementations MAY choose to perform different levels of resolution. @@ -177,7 +172,7 @@ and different implementations MAY choose to perform different levels of resoluti > calling the `selectKeys(keys)` method of its _resolved value_ > did not emit an error. > - Using a _variable_, the _resolved value_ of an _expression_ -> could be used as an _operand_ or _option_ value if +> could be used as an _operand_ or _option value_ if > calling the `getValue()` method of its _resolved value_ did not emit an error. > In this use case, the `resolvedOptions()` method could also > provide a set of option values that could be taken into account by the called function. @@ -246,8 +241,7 @@ Its _resolved value_ is defined by _literal resolution_. the character sequence of the _text_ or _literal_ after any character escape has been converted to the escaped character. -When a _literal_ is used as an _operand_ -or on the right-hand side of an _option_, +When a _literal_ is used as an _operand_ or as an _option value_, the formatting function MUST treat its _resolved value_ the same whether its value was originally a _quoted literal_ or an _unquoted literal_. @@ -329,7 +323,7 @@ the following steps are taken: - The resolved mapping of _options_. - If the _expression_ includes an _operand_, its _resolved value_. - The form that resolved _operand_ and _option_ values take is implementation-defined. + The form that resolved _operand_ and _option values_ take is implementation-defined. An implementation MAY pass additional arguments to the _function handler_, as long as reasonable precautions are taken to keep the function interface @@ -337,7 +331,7 @@ the following steps are taken: 6. If the call succeeds, resolve the value of the _expression_ as the result of that function call. - The value MUST NOT be marked as a literal option value. + The value MUST NOT be marked as a _literal_ _option value_. If the call fails or does not return a valid value, emit the appropriate _Message Function Error_ for the failure. @@ -363,7 +357,7 @@ An implementation MAY allow custom functions to be defined by users. Implementations that provide a means for defining custom functions MUST provide a means for _function handlers_ to return _resolved values_ that contain enough information -to be used as _operands_ or _option_ values in subsequent _expressions_. +to be used as _operands_ or _option values_ in subsequent _expressions_. The _resolved value_ returned by a _function handler_ MAY be different from the value of the _operand_ of the _function_. @@ -399,12 +393,12 @@ For each _option_: 1. Let `res` be a new empty mapping. 1. For each _option_: 1. Let `id` be the string value of the _identifier_ of the _option_. - 1. Let `rv` be the _resolved value_ of the _option_ value. + 1. Let `rv` be the _resolved value_ of the _option value_. 1. If `rv` is a _fallback value_: 1. If supported, emit a _Bad Option_ error. 1. Else: - 1. If the _option_ value consists of a _literal_: - 1. Mark `rv` as a literal option value. + 1. If the _option value_ consists of a _literal_: + 1. Mark `rv` as a _literal_ _option value_. 1. Set `res[id]` to be `rv`. 1. Return `res`. @@ -428,7 +422,7 @@ The _resolved value_ of _markup_ includes the following fields: - The type of the markup: open, standalone, or close - The _identifier_ of the _markup_ -- The resolved _options_ values after _option resolution_. +- The resolved mapping of _options_ after _option resolution_. If the resolved mapping of _options_ includes any _`u:` options_ supported by the implementation, process them as specified. @@ -440,8 +434,8 @@ The resolution of _markup_ MUST always succeed. A **_fallback value_** is the _resolved value_ for an _expression_ or _variable_ when that _expression_ or _variable_ fails to resolve. -It contains a string representation that is used for its formatting, -and no option values. +It contains a string representation that is used for its formatting. +All _options_ are removed. The _resolved value_ of _text_, _literal_, and _markup_ MUST NOT be a _fallback value_. @@ -453,7 +447,7 @@ An _expression_ fails to resolve when: - A _variable_ used as its _operand_ resolves to a _fallback value_. Note that an _expression_ does not necessarily fail to resolve - if an _option_ resolves with a _fallback value_. + if an _option value_ resolves with a _fallback value_. - No _function handler_ is found for a _function_ _identifier_. - Calling a _function handler_ fails or does not return a valid value. diff --git a/spec/functions/README.md b/spec/functions/README.md index 13b3fc9109..e0ed74f1f6 100644 --- a/spec/functions/README.md +++ b/spec/functions/README.md @@ -25,11 +25,11 @@ emit an _Unknown Function_ error for that _function_'s _identifier_. To _accept_ an _option_ means that a _function handler_ MUST NOT emit a _Bad Option_ error for that _option_'s _identifier_ when used with the _function_ it is defined for -and MUST NOT emit a _Bad Option_ error for any of the _option_ values +and MUST NOT emit a _Bad Option_ error for any of the _option values_ defined for that _option_. Accepting a _function_ or its _options_ does not mean that a particular output is produced. Implementations MAY emit an _Unsupported Operation_ error for _options_ -or _option_ values that they cannot support. +or _option values_ that they cannot support. _Functions_ can define _options_. An _option_ can be REQUIRED or RECOMMENDED. @@ -54,11 +54,11 @@ by any version of this specification for _default functions_. Such _options_ MUST use an implementation-specific _namespace_. Implementations MAY _accept_, for _options_ defined in this specification, -_option_ values which are not defined in this specification. +_option values_ which are not defined in this specification. However, such values might become defined with a different meaning in the future, including with a different, incompatible name or using an incompatible value space. -Supporting implementation-specific _option_ values for _default functions_ is NOT RECOMMENDED. +Supporting implementation-specific _option values_ for _default functions_ is NOT RECOMMENDED. Implementations MAY _accept_, for _operands_ or _options_ defined in this specification, values with implementation-defined types. @@ -71,11 +71,11 @@ Such values can be useful to users in cases where local usage and support exists > - A Java implementation might _accept_ a `java.time.chrono.Chronology` object > as a value for the _date/time override option_ `calendar` -Future versions of this specification MAY define additional _options_ and _option_ values, +Future versions of this specification MAY define additional _options_ and _option values_, subject to the rules in the [Stability Policy](#stability-policy), for _functions_ found in this specification. As implementations are permitted to ignore _options_ that they do not support, -it is possible to write _messages_ using _options_ not defined below +it is possible to write _messages_ using _options_ not defined here which currently format with no error, but which could produce errors when formatted with a later edition of this specification. Therefore, using _options_ not explicitly defined here is NOT RECOMMENDED. diff --git a/spec/functions/datetime.md b/spec/functions/datetime.md index b71aab22fc..827bb72994 100644 --- a/spec/functions/datetime.md +++ b/spec/functions/datetime.md @@ -45,12 +45,12 @@ a _Bad Option_ error is emitted and a _fallback value_ used as the _resolved value_ of the _expression_. If the _operand_ of the _expression_ is an implementation-defined date/time type, -it can include _style options_, _field options_, or other option values. +it can include _style options_, _field options_, or other _options_. These are included in the resolved option values of the _expression_, -with _options_ on the _expression_ taking priority over any option values of the _operand_. +with _options_ on the _expression_ taking priority over any options of the _operand_. > [!NOTE] -> The names of _options_ and their _values_ were derived from the +> The names of _options_ and their _option values_ were derived from the > [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions#description) > in JavaScript's `Intl.DateTimeFormat`. @@ -58,7 +58,7 @@ with _options_ on the _expression_ taking priority over any option values of the **_Style options_** pertain to the overall styling or appearance of the formatted output. -The function `:datetime` has these _style options_. +The following _style options_ are REQUIRED to be available on the function `:datetime`: - `dateStyle` - `full` @@ -80,7 +80,7 @@ and what format to use for that field. > _Field options_ do not have default values because they are only to be used > to compose the formatter. -The function `:datetime` has the following _field options_: +The following _field options_ are REQUIRED to be available on the function `:datetime`: - `weekday` - `long` @@ -149,7 +149,7 @@ All other _operand_ values produce a _Bad Operand_ error. The function `:date` has these _options_: -- `style` +- `style` \[REQUIRED\] - `full` - `long` - `medium` (default) @@ -158,7 +158,7 @@ The function `:date` has these _options_: If the _operand_ of the _expression_ is an implementation-defined date/time type, it can include other option values. -Any _operand_ option values matching the `:datetime` _style options_ or _field options_ are ignored, +Any _operand_ options matching the `:datetime` _style options_ or _field options_ are ignored, as is any `style` option. ##### Resolved Value @@ -168,7 +168,7 @@ is implementation-defined. An implementation MAY emit a _Bad Operand_ or _Bad Option_ error (as appropriate) when a _variable_ annotated directly or indirectly by a `:date` _annotation_ -is used as an _operand_ or an _option_ value. +is used as an _operand_ or an _option value_. #### The `:time` function @@ -189,7 +189,7 @@ All other _operand_ values produce a _Bad Operand_ error. The function `:time` has these _options_: -- `style` +- `style` \[REQUIRED\] - `full` - `long` - `medium` @@ -198,7 +198,7 @@ The function `:time` has these _options_: If the _operand_ of the _expression_ is an implementation-defined date/time type, it can include other option values. -Any _operand_ option values matching the `:datetime` _style options_ or _field options_ are ignored, +Any _operand_ options matching the `:datetime` _style options_ or _field options_ are ignored, as is any `style` option. ##### Resolved Value @@ -208,7 +208,7 @@ is implementation-defined. An implementation MAY emit a _Bad Operand_ or _Bad Option_ error (as appropriate) when a _variable_ annotated directly or indirectly by a `:time` _annotation_ -is used as an _operand_ or an _option_ value. +is used as an _operand_ or an _option value_. #### Date and Time Operands @@ -271,20 +271,7 @@ or embedded in an implementation-defined date/time _operand_ value. > These _options_ do not have default values because they are only to be used > as overrides for locale-and-value dependent implementation-defined defaults. -The following _option_ and its values are REQUIRED to be available on -the functions `:datetime` and `:time`: - -- `hour12` - - `true` - - `false` - -The following _option_ and its values are RECOMMENDED to be available on -the functions `:datetime`, `:date`, and `:time`. - -- `calendar` - - valid [Unicode Calendar Identifier](https://unicode.org/reports/tr35/tr35.html#UnicodeCalendarIdentifier) - -The following _option_ and its values are REQUIRED to be available on +The following _option_ is REQUIRED to be available on the functions `:datetime`, `:date`, and `:time`. - `timeZone` @@ -300,3 +287,16 @@ the functions `:datetime`, `:date`, and `:time`. > into a [floating](https://www.w3.org/TR/timezone/#floating) time value > (sometimes called a _plain_ or _local_ time value) by removing > the association with a specific time zone. + +The following _option_ is REQUIRED to be available on +the functions `:datetime` and `:time`: + +- `hour12` + - `true` + - `false` + +The following _option_ is RECOMMENDED to be available on +the functions `:datetime`, `:date`, and `:time`. + +- `calendar` + - valid [Unicode Calendar Identifier](https://unicode.org/reports/tr35/tr35.html#UnicodeCalendarIdentifier) diff --git a/spec/functions/number.md b/spec/functions/number.md index 7c22b01466..f791b304f0 100644 --- a/spec/functions/number.md +++ b/spec/functions/number.md @@ -16,11 +16,11 @@ In general, the default values for such options depend on the locale, the value of other options, or both. > [!NOTE] -> The names of _options_ and their _values_ were derived from the +> The names of _options_ and their _option values_ were derived from the > [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) > in JavaScript's `Intl.NumberFormat`. -The following options and their values are REQUIRED to be available on the function `:number`: +The following _options_ are REQUIRED to be available on the function `:number`: - `select` (see [Number Selection](#number-selection) below) - `plural` (default) @@ -38,15 +38,15 @@ The following options and their values are REQUIRED to be available on the funct - `never` - `min2` - `minimumIntegerDigits` - - ([digit size option](#digit-size-options), default: `1`) + - _digit size option_, default: `1` - `minimumFractionDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `maximumFractionDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `minimumSignificantDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `maximumSignificantDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `trailingZeroDisplay` - `auto` (default) - `stripIfInteger` @@ -71,7 +71,7 @@ If the _operand_ of the _expression_ is an implementation-defined type, such as the _resolved value_ of an _expression_ with a `:number` or `:integer` _annotation_, it can include option values. These are included in the resolved option values of the _expression_, -with _options_ on the _expression_ taking priority over any option values of the _operand_. +with _options_ on the _expression_ taking priority over any options of the _operand_. > For example, the _placeholder_ in this _message_: > @@ -111,11 +111,11 @@ In general, the default values for such options depend on the locale, the value of other options, or both. > [!NOTE] -> The names of _options_ and their _values_ were derived from the +> The names of _options_ and their _option values_ were derived from the > [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) > in JavaScript's `Intl.NumberFormat`. -The following options and their values are REQUIRED to be available on the function `:integer`: +The following _options_ are REQUIRED to be available on the function `:integer`: - `select` (see [Number Selection](#number-selection) below) - `plural` (default) @@ -133,16 +133,16 @@ The following options and their values are REQUIRED to be available on the funct - `never` - `min2` - `minimumIntegerDigits` - - ([digit size option](#digit-size-options), default: `1`) + - _digit size option_, default: `1` - `maximumSignificantDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ If the _operand_ of the _expression_ is an implementation-defined type, such as the _resolved value_ of an _expression_ with a `:number` or `:integer` _annotation_, it can include option values. In general, these are included in the resolved option values of the _expression_, -with _options_ on the _expression_ taking priority over any option values of the _operand_. -Option values with the following names are however discarded if included in the _operand_: +with _options_ on the _expression_ taking priority over any options of the _operand_. +Options with the following names are however discarded if included in the _operand_: - `minimumFractionDigits` - `maximumFractionDigits` @@ -188,19 +188,19 @@ The function `:math` requires a [Number Operand](#number-operands) as its _opera ##### Options -The options on `:math` are exclusive with each other, -and exactly one option is always required. -The options do not have default values. +The _options_ on `:math` are exclusive with each other, +and exactly one _option_ is always required. +The _options_ do not have default values. -The following options and their values are REQUIRED to be available on the function `:math`: +The following _options_ are REQUIRED to be available on the function `:math`: - `add` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `subtract` - - ([digit size option](#digit-size-options)) + - _digit size option_ -If no options or more than one option is set, -or if an _option_ value is not a [digit size option](#digit-size-options), +If no _options_ or more than one _option_ is set, +or if an _option value_ is not a _digit size option_, a _Bad Option_ error is emitted and a _fallback value_ used as the _resolved value_ of the _expression_. @@ -210,13 +210,13 @@ The _resolved value_ of an _expression_ with a `:math` _function_ contains the implementation-defined numeric value of the _operand_ of the annotated _expression_. -If the `add` option is set, +If the `add` _option_ is set, the numeric value of the _resolved value_ is formed by incrementing -the numeric value of the _operand_ by the integer value of the digit size option value. +the numeric value of the _operand_ by the integer value of the _digit size option_. -If the `subtract` option is set, +If the `subtract` _option_ is set, the numeric value of the _resolved value_ is formed by decrementing -the numeric value of the _operand_ by the integer value of the digit size option value. +the numeric value of the _operand_ by the integer value of the _digit size option_. If the _operand_ of the _expression_ is an implementation-defined numeric type, such as the _resolved value_ of an _expression_ with a `:number` or `:integer` _annotation_, @@ -249,10 +249,10 @@ which are a specialized form of numeric formatting. The _operand_ of the `:currency` function can be one of any number of implementation-defined types, each of which contains a numerical `value` and a `currency`; -or it can be a [Number Operand](#number-operands), as long as the option +or it can be a [Number Operand](#number-operands), as long as the _option_ `currency` is provided. -The option `currency` MUST NOT be used to override the currency of an implementation-defined type. -Using this option in such a case results in a _Bad Option_ error. +The _option_ `currency` MUST NOT be used to override the currency of an implementation-defined type. +Using this _option_ in such a case results in a _Bad Option_ error. The value of the _operand_'s `currency` MUST be either a string containing a well-formed [Unicode Currency Identifier](https://unicode.org/reports/tr35/tr35.html#UnicodeCurrencyIdentifier) @@ -309,7 +309,7 @@ Setting some other number of `fractionDigits` allows greater precision display (such as when performing currency conversions or other specialized operations) or disabling fraction digits if set to `0`. -The _option_ `trailingZeroDisplay` has a value `stripIfInteger` that is useful +The _option_ `trailingZeroDisplay` has an _option value_ `stripIfInteger` that is useful for displaying currencies with their fraction digits removed when the fraction part of the _operand_ is zero. This is sometimes used in _messages_ to make the displayed value omit the fraction part @@ -333,16 +333,16 @@ automatically. > The special price is $5.01. > ``` -Implementations MAY internally alias option values that they do not have data or a backing implementation for. +Implementations MAY internally alias _option values_ that they do not have data or a backing implementation for. Notably, the `currencyDisplay` option has a rich set of values that mirrors developments in CLDR data. Some implementations might not be able to produce all of these formats for every currency. > [!NOTE] -> Except where noted otherwise, the names of _options_ and their _values_ were derived from the +> Except where noted otherwise, the names of _options_ and their _option values_ were derived from the > [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) > in JavaScript's `Intl.NumberFormat`. -The following options and their values are REQUIRED to be available on the function `:currency`: +The following _options_ are REQUIRED to be available on the function `:currency`: - `currency` - well-formed [Unicode Currency Identifier](https://unicode.org/reports/tr35/tr35.html#UnicodeCurrencyIdentifier) @@ -362,14 +362,14 @@ The following options and their values are REQUIRED to be available on the funct - `never` - `min2` - `minimumIntegerDigits` - - ([digit size option](#digit-size-options), default: `1`) + - _digit size option_, default: `1` - `fractionDigits` (unlike number/integer formats, the fraction digits for currency formatting are fixed) - `auto` (default) (the number of digits used by the currency) - - ([digit size option](#digit-size-options)) + - _digit size option_ - `minimumSignificantDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `maximumSignificantDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `trailingZeroDisplay` - `auto` (default) - `stripIfInteger` @@ -394,7 +394,7 @@ If the _operand_ of the _expression_ is an implementation-defined type, such as the _resolved value_ of an _expression_ with a `:currency` _annotation_, it can include option values. These are included in the resolved option values of the _expression_, -with _options_ on the _expression_ taking priority over any option values of the _operand_. +with _options_ on the _expression_ taking priority over any options of the _operand_. > For example, the _placeholder_ in this _message_: > @@ -465,7 +465,7 @@ In general, the default values for such _options_ depend on the locale, the unit, the value of other _options_, or all of these. -The following options and their values are REQUIRED to be available on the function `:unit`, +The following _options_ are REQUIRED to be available on the function `:unit`, unless otherwise indicated: - `unit` @@ -490,15 +490,15 @@ unless otherwise indicated: - `never` - `min2` - `minimumIntegerDigits` - - ([digit size option](#digit-size-options), default: `1`) + - _digit size option_, default: `1` - `minimumFractionDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `maximumFractionDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `minimumSignificantDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `maximumSignificantDigits` - - ([digit size option](#digit-size-options)) + - _digit size option_ - `roundingPriority` - `auto` (default) - `morePrecision` @@ -518,9 +518,9 @@ unless otherwise indicated: If the _operand_ of the _expression_ is an implementation-defined type, such as the _resolved value_ of an _expression_ with a `:unit` _annotation_, -it can include _option_ values. -These are included in the resolved _option_ values of the _expression_, -with _options_ on the _expression_ taking priority over any _option_ values of the _operand_. +it can include option values. +These are included in the resolved option values of the _expression_, +with _options_ on the _expression_ taking priority over any options of the _operand_. > For example, the _placeholder_ in this _message_: > @@ -537,13 +537,13 @@ with _options_ on the _expression_ taking priority over any _option_ values of t The _resolved value_ of an _expression_ with a `:unit` _function_ consist of an implementation-defined unit value of the _operand_ of the annotated _expression_, -together with the resolved _options_ and their resolved values. +together with the resolved options and their resolved values. ##### Unit Conversion Implementations MAY support conversion to the locale's preferred units via the `usage` _option_. Implementing this _option_ is optional. -Not all `usage` values are compatible with a given unit. +Not all `usage` _option values_ are compatible with a given unit. Implementations SHOULD emit an _Unsupported Operation_ error if the requested conversion is not supported. > For example, trying to convert a `length` unit (such as "meters") @@ -573,7 +573,7 @@ Implementations MUST NOT substitute the unit without performing the associated c #### Number Operands The _operand_ of a number function is either an implementation-defined type or -a literal whose contents match the following `number-literal` production. +a _literal_ whose contents match the following `number-literal` production. All other values produce a _Bad Operand_ error. ```abnf @@ -610,34 +610,36 @@ number-literal = ["-"] (%x30 / (%x31-39 *DIGIT)) ["." 1*DIGIT] [%i"e" ["-" / "+" #### Digit Size Options -Some _options_ of number _functions_ are defined to take a "digit size option". +Some _options_ of number _functions_ are defined to take a _digit size option_. The _function handlers_ for number _functions_ use these _options_ to control aspects of numeric display such as the number of fraction, integer, or significant digits. -A "digit size option" is an _option_ value that the _function_ interprets -as a small integer value greater than or equal to zero. +A **_digit size option_** is an _option_ +whose _option value_ is interpreted by the _function_ +as a small integer greater than or equal to zero. Implementations MAY define an upper limit on the _resolved value_ -of a digit size option consistent with that implementation's practical limits. +of a _digit size option_ consistent with that implementation's practical limits. -In most cases, the value of a digit size option will be a string that +In most cases, the value of a _digit size option_ will be a string that encodes the value as a non-negative integer. -Implementations MAY also accept implementation-defined types as the value. -When provided as a string, the representation of a digit size option matches the following ABNF: +Implementations MAY also accept implementation-defined types as the _option value_. +When provided as a string, the representation of a _digit size option_ matches the following ABNF: ```abnf digit-size-option = "0" / (("1"-"9") [DIGIT]) ``` -If the value of a digit size option does not evaluate as a non-negative integer, -or if the value exceeds any implementation-defined upper limit -or any option-specific lower limit, a _Bad Option_ error is emitted. +If the value of a _digit size option_ does not evaluate as a non-negative integer, +or if the value exceeds any implementation-defined and option-specific upper or lower limit, +a _Bad Option_ error is emitted. #### Number Selection -The value of the `select` _option_ MUST be set by a _literal_, -as otherwise the _message_ might not be translatable. -If this value is set by a _variable_ or -the option value of an implementation-defined type used as an _operand_, +The _option value_ of the `select` _option_ MUST be set by a _literal_. +Allowing a _variable_ _option value_ for `select` would produce a _message_ that +is impossible to translate because the set of _keys_ is tied to the _selector_ chosen. +If the _option value_ is a _variable_ or +if the `select` option is set by an implementation-defined type used as an _operand_, a _Bad Option Error_ is emitted and the _resolved value_ of the expression MUST NOT support selection. The formatting of the _resolved value_ is not affected by the `select` _option_. @@ -676,7 +678,7 @@ numeric selectors perform as described below. ##### Default Value of `select` Option -The value `plural` is the default for the option `select` +The _option value_ `plural` is the default for the _option_ `select` because it is the most common use case for numeric selection. It can be used for exact value matches but also allows for the grammatical needs of languages using CLDR's plural rules. @@ -702,7 +704,7 @@ but can cause problems in target locales that the original developer is not cons Rule selection is intended to support the grammatical matching needs of different languages/locales in order to support plural or ordinal numeric values. -If the _option_ `select` is set to `exact`, rule-based selection is not used. +If the `select` _option value_ is `exact`, rule-based selection is not used. Otherwise rule selection matches the _operand_, as modified by function _options_, to exactly one of these keywords: `zero`, `one`, `two`, `few`, `many`, or `other`. The keyword `other` is the default. @@ -722,12 +724,12 @@ Apply the rules to the _resolved value_ of the _operand_ and the relevant functi and return the resulting keyword. If no rules match, return `other`. -If the option `select` is set to `plural`, the rules applied to selection SHOULD be +If the `select` _option value_ is `plural`, the rules applied to selection SHOULD be the CLDR plural rule data of type `cardinal`. See [charts](https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html) for examples. -If the option `select` is set to `ordinal`, the rules applied to selection SHOULD be +If the `select` _option value_ is `ordinal`, the rules applied to selection SHOULD be the CLDR plural rule data of type `ordinal`. See [charts](https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html) for examples. diff --git a/spec/functions/string.md b/spec/functions/string.md index be6d5be5fa..d15ef4510a 100644 --- a/spec/functions/string.md +++ b/spec/functions/string.md @@ -27,7 +27,7 @@ All other values produce a _Bad Operand_ error. The function `:string` has no _options_. > [!NOTE] -> While `:string` has no built- in _options_, +> While `:string` has no built-in _options_, > _options_ in the `u:` _namespace_ can be used. > For example: > diff --git a/spec/intro.md b/spec/intro.md index 433f0e3ee5..9e0e4036ed 100644 --- a/spec/intro.md +++ b/spec/intro.md @@ -91,7 +91,7 @@ of any syntax defined in this specification. Updates to this specification will not remove any _default functions_. -Updates to this specification will not remove any _options_ or _option_ values +Updates to this specification will not remove any _options_ or _option values_ defined for _default functions_. > [!IMPORTANT] @@ -99,7 +99,7 @@ defined for _default functions_. > the provisions of this stability policy. > > _Functions_ or _options_ marked as **Draft** are not stable. -> Their name, _operands_, and _options_/_values_, and other requirements +> Their name, _operands_, and _options_/_option values_, and other requirements > might change or be removed before being declared **Stable** in a future release. > [!NOTE] @@ -142,8 +142,8 @@ based on this version being invalid. > - Future versions may define additional _default functions_. > or may reserve the names of _functions_ for the purposes of interoperability. > - Future versions may define additional _options_ to existing functions. -> - Future versions may define additional _option_ values for existing _options_. -> - Future versions may deprecate (but not remove) _keywords_, _functions_, _options_, or _option_ values. +> - Future versions may define additional _option values_ for existing _options_. +> - Future versions may deprecate (but not remove) _keywords_, _functions_, _options_, or _option values_. > - Future versions of this specification may introduce changes > to the data model that would result in future data model representations > not being valid for implementations of this version of the data model. diff --git a/spec/syntax.md b/spec/syntax.md index 3a18886b90..f28dd612fd 100644 --- a/spec/syntax.md +++ b/spec/syntax.md @@ -568,10 +568,10 @@ function = ":" identifier *(s option) An **_option_** is a key-value pair containing a named argument that is passed to a _function_. -An _option_ has an _identifier_ and a _value_. -The _identifier_ is separated from the _value_ by an U+003D EQUALS SIGN `=` along with +An _option_ has an _identifier_ and an _option value_. +The _identifier_ is separated from the _option value_ by an U+003D EQUALS SIGN `=` along with optional whitespace. -The value of an _option_ can be either a _literal_ or a _variable_. +The **_option value_** can be either a _literal_ or a _variable_. Multiple _options_ are permitted in a _function_. _Options_ are separated from the preceding _function_ _identifier_ @@ -660,7 +660,7 @@ and they can be treated as code comments. _Attributes_ are prefixed by a U+0040 COMMERCIAL AT `@` sign, followed by an _identifier_. -An _attribute_ MAY have a _literal_ _value_ which is separated from the _identifier_ +An _attribute_ MAY have a _literal_ value which is separated from the _identifier_ by an U+003D EQUALS SIGN `=` along with optional whitespace. Multiple _attributes_ are permitted in an _expression_ or _markup_. @@ -712,7 +712,7 @@ of _text_ in various parts of a _message_. A _literal_ can appear as a _key_ value, as the _operand_ of a _literal-expression_, -or in the value of an _option_. +or as an _option value_. A _literal_ MAY include any Unicode code point except for U+0000 NULL. All code points are preserved. @@ -955,7 +955,7 @@ following mechanisms to make messages display intelligibly in plain-text editors 2. Use the 'local-effect' bidi marks `U+061C ARABIC LETTER MARK`, `U+200E LEFT-TO-RIGHT MARK` or `U+200F RIGHT-TO-LEFT MARK` as permitted by the ABNF before or after _identifiers_, - _names_, unquoted _literals_, or _option_ values, + _names_, unquoted _literals_, or _option values_, especially when the values contain a mix of neutral, weakly directional, and strongly directional characters. diff --git a/spec/u-namespace.md b/spec/u-namespace.md index 375b2739a1..38a278af93 100644 --- a/spec/u-namespace.md +++ b/spec/u-namespace.md @@ -34,11 +34,11 @@ or any other structured formatted results. Ignored when formatting a message to a string. -The value of the `u:id` _option_ MUST be a _literal_ or a +The `u:id` _option value_ MUST be a _literal_ or a _variable_ whose _resolved value_ is either a string or can be resolved to a string without error. For other values, a _Bad Option_ error is emitted -and the `u:id` option is ignored. +and the `u:id` _option_ and its _option value_ are ignored. #### `u:locale` @@ -56,7 +56,7 @@ language tags, or an implementation-defined list of such tags. If this _option_ is set on _markup_, a _Bad Option_ error is emitted -and the value of the `u:locale` _option_ is ignored. +and the `u:locale` _option_ and its _option value_ are ignored. During processing, the `u:locale` _option_ MUST be removed from the resolved mapping of _options_ @@ -76,7 +76,7 @@ When the value of `u:locale` is set by a _variable_, implementations MAY support non-string values otherwise representing locales. Implementations MAY emit a _Bad Option_ error -and MAY ignore the value of the `u:locale` _option_ as a whole +and MAY ignore the `u:locale` _option_ and _option value_ as a whole or any of the entries in the list of language tags. This might be because the locale specified is not supported or because the language tag is not well-formed, @@ -90,16 +90,16 @@ Replaces the base directionality defined in the _function context_ for this _expression_ and applies bidirectional isolation to it. -If this option is set on _markup_, a _Bad Option_ error is emitted -and the value of the `u:dir` option is ignored. +If this _option_ is set on _markup_, a _Bad Option_ error is emitted +and the `u:dir` _option_ and its _option value_ are ignored. -During processing, the `u:dir` option +During processing, the `u:dir` _option_ MUST be removed from the resolved mapping of _options_ before calling the _function handler_. Its value is retained in the _resolved value_ of the _expression_. -The value of the `u:dir` _option_ MUST be one of the following _literal_ values -or a _variable_ whose _resolved value_ is one of these _literals_: +The `u:dir` _option value_ MUST be one of the following _literal_ values +or a _variable_ whose _resolved value_ is one of the following strings: - `ltr`: left-to-right directionality - `rtl`: right-to-left directionality - `auto`: directionality determined from _expression_ contents @@ -108,4 +108,4 @@ or a _variable_ whose _resolved value_ is one of these _literals_: requiring isolation of the _expression_ value. For other values, a _Bad Option_ error is emitted -and the value of the `u:dir` option is ignored. +and the `u:dir` _option_ and its _option value_ are ignored.