Skip to content

Fix normative vs. non-normative keywords in formatting.md #411

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 10, 2023
Merged

Fix normative vs. non-normative keywords in formatting.md #411

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bfb4427
Minor formatting fixes
eemeli Jul 3, 2023
9d60067
Apply suggestions from code review
eemeli Jul 4, 2023
9c09b53
Apply suggestions from code review
eemeli Jul 6, 2023
ea3f6e8
Apply suggestions from code review
eemeli Jul 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 39 additions & 15 deletions spec/formatting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,10 +49,11 @@ At a minimum, it includes:
This will be passed on to formatting functions.

- Information on the base directionality of the message and its _text_ tokens.
This will be used by strategies for bidirectional isolation.
This will be used by strategies for bidirectional isolation,
and can be used to set the base direction of the _message_ upon display.

- A mapping of string identifiers to values,
defining variable values that may be used during _variable resolution_.
defining variable values that are available during _variable resolution_.
This is often determined by a user-provided argument of a formatting function call.

- The _function registry_,
Expand All @@ -68,7 +69,7 @@ Implementations MAY include additional fields in their _formatting context_.
_Expressions_ are used in _declarations_, _selectors_, and _patterns_.

In a _declaration_, the resolved value of the _expression_ is assigned to a _variable_,
which may then be used in other _expressions_.
which is available for use by later _expressions_.
As such a _variable_ MAY then be referenced in different ways,
implementations SHOULD NOT immediately fully format the value for output.

Expand Down Expand Up @@ -99,8 +100,10 @@ one of the following is used to resolve the value of the _expression_:
depending on the shape of the _operand_.
- Else, if the _expression_ has a _function_ _annotation_,
its resolved value is defined by _function resolution_.
- Else, the _expression_ has a _reserved_ _annotation_,
and a fallback value is used as its value.
- Else, the _expression_ has a _reserved_ _annotation_.
If the _annotation_ uses a `private-start` character that the implementation supports,
its value is resolved according to the implementation's specification.
Else, an Unsupported Expression error is emitted and a fallback value is used as its value.

### Literal Resolution

Expand Down Expand Up @@ -174,15 +177,15 @@ the following steps are taken:

### Fallback Resolution

The resolution of an _expression_ may fail in the following cases:
A **_fallback value_** is the resolved value emitted when an _expression_ cannot be resolved.

An _expression_ fails to resolve when:

- A _variable_ _operand_ fails to resolve.
- A _function_ _annotation_ fails to resolve.
- The _expression_ has a _reserved_ _annotation_.

In each such case, an error MUST be emitted
and a **_fallback value_** used for the _expression_.
This value depends on the shape of the _expression_:
The _fallback value_ depends on the contents of the _expression_:

- _expression_ with _literal_ _operand_: U+007C VERTICAL LINE `|`
followed by the value of the Literal,
Expand Down Expand Up @@ -308,9 +311,10 @@ Next, using `res`, resolve the preferential order for all message keys:
The method MatchSelectorKeys is determined by the implementation.
It takes as arguments a resolved _selector_ value `rv` and a list of string keys `keys`,
and returns a list of string keys in preferential order.
The returned list must only contain unique elements of the input list `keys`,
and it may be empty.
The most preferred key is first, with the rest sorted by decreasing preference.
The returned list MUST contain only unique elements of the input list `keys`.
The returned list MAY be empty.
The most-preferred key is first,
with each successive key appearing in order by decreasing preference.

### Filter Variants

Expand Down Expand Up @@ -493,7 +497,7 @@ when * {Other match}
## Formatting

After _pattern selection_,
each _text_ and _expression_ part of the selected _pattern_ must be resolved and formatted.
each _text_ and _expression_ part of the selected _pattern_ is resolved and formatted.

_Formatting_ is a mostly implementation-defined process,
as it depends on the implementation's shape for resolved values
Expand Down Expand Up @@ -691,7 +695,7 @@ These are divided into the following categories:
- **Unresolved Variable errors** occur when a variable reference cannot be resolved.

> For example, attempting to format either of the following messages
> must result in an Unresolved Variable error if done within a context that
> would result in an Unresolved Variable error if done within a context that
> does not provide for the variable reference `$var` to be successfully resolved:
>
> ```
Expand All @@ -708,7 +712,7 @@ These are divided into the following categories:
a reference to a function which cannot be resolved.

> For example, attempting to format either of the following messages
> must result in an Unknown Function error if done within a context that
> would result in an Unknown Function error if done within a context that
> does not provide for the function `:func` to be successfully resolved:
>
> ```
Expand All @@ -721,6 +725,26 @@ These are divided into the following categories:
> when * {The value is not one.}
> ```

- **Unsupported Expression errors** occur when an expression uses
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use singular instead of plural:

Suggested change
- **Unsupported Expression errors** occur when an expression uses
An **Unsupported Expression error** occurs when an expression uses

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current plural language matches that used by all the other errors. Could fixes to the style used for the error descriptions be handled as a separate PR, rather than further increasing the scope of this PR?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to favor "not digging the hole deeper" when committing text, but since we'll probably merge this in an hour, I can come back and make a more holistic set of edits later.

With regard to this comment (and noting that it rhymes with other comments in other PRs), the style I prefer is something like:

Term is (definition here).

(discussion of term's attributes, usage, triggers, etc., with term referencing the definition)

I tend to prefer singular, because automatic linking of references to the definition is easier when the term is originally singular. Unlike W3C, we don't have markup to use for alternate forms of the term and will have to write the link generation eventually as a script (if we decide we want linking). 🤷

syntax reserved for future standardization,
or for private implementation use that is not supported by the current implementation.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should try to be consistent when talking about private use. Also, remember your formatting. I'd suggest:

Suggested change
or for private implementation use that is not supported by the current implementation.
or for _annotations_ that use a _private-use_ sequence unsupported by the current implementation.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your proposed change does not match our current description of reserved, which does not so differentiate annotations reserved for future spec versions compared to those reserved for private implementation use. Furthermore, we do not have a definition of private-use to refer to.

It's clear that the language around reserved could be updated, but that really ought to happen holistically rather than as a part of this PR, which so far is only touching the formatting parts of the spec.


> For example, attempting to format this message
> would always result in an Unsupported Expression error:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> would always result in an Unsupported Expression error:
would always result in an _Unsupported Expression error_:

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could this fix also be included in a separate PR of all our error definitions and mentions? The current proposal matches the style used by all our current error references.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See ⬆️

The current error references should be edited to italicize terms like our spec's front matter says we do, so this change really should be committed and other, inconsistent, text fixed. I will file an issue to do formatting and take that as an action after I click "Comment" here 😉

>
> ```
> {The value is {@horse}.}
> ```
>
> Attempting to format this message would result in an Unsupported Expression error
> if done within a context that does not support the `^` private use sigil:
Comment on lines +739 to +740
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Formatting and a small wording change:

Suggested change
> Attempting to format this message would result in an Unsupported Expression error
> if done within a context that does not support the `^` private use sigil:
> Formatting this message would result in an _Unsupported Expression error_
> if done within a context that does not support the `^` _private-use_ sigil:

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This too seems like it should be a part of a separate subsequent PR updating our error definitions, as the current language matches that used by all our other error examples.

>
> ```
> match {|horse| ^private}
> when 1 {The value is one.}
> when * {The value is not one.}
> ```

- **Selection errors** occur when message selection fails.

- **Selector errors** are failures in the matching of a key to a specific selector.
Expand Down