Skip to content

Clear up some ambiguities in terminology in formatting.md #723

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

Closed
wants to merge 1 commit into from
Closed

Clear up some ambiguities in terminology in formatting.md #723

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
9 changes: 5 additions & 4 deletions spec/formatting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,15 @@ an appropriate error MUST be emitted and a _fallback value_ MAY be used as the f

Formatting of a _message_ is defined by the following operations:

- **_Expression and Markup Resolution_** determines the value of an _expression_ or _markup_,
- **_Expression and Markup Resolution_** determines the resolved value of an _expression_ or _markup_,
with reference to the current _formatting context_.
This can include multiple steps,
such as looking up the value of a variable and calling formatting functions.
The form of the resolved value is implementation defined and the
value might not be evaluated or formatted yet.
However, it needs to be "formattable", i.e. it contains everything required
by the eventual formatting.
However, if it is the resolved value of an expression with a function
Copy link
Collaborator

Choose a reason for hiding this comment

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

Why include the mention "with a function" here? Also, it's not really our functions that are "formatting" or "selection" functions, it's the resolved values that may or may not support either, or both.

Copy link
Member

Choose a reason for hiding this comment

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

I agree with @eemeli. What's more, this is overly specific to expression and forgets about markup. Perhaps instead of trying to list everything separately we could say:

Suggested change
However, if it is the resolved value of an expression with a function
However, it needs to be "formattable", that is, it contains everything required
during later steps in the formatting process (such as selection, formatting, or output
of the _expression_ or _markup_.

Note that I was tempted to add "... as a string" at the end of the above, but formatToParts behavior shouldn't be omitted.

Copy link
Member Author

Choose a reason for hiding this comment

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

Well, the current statement

"However, it needs to be "formattable", i.e. it contains everything required by the eventual formatting."

is absolutely wrong. The resolved value for a an expression does not have to be "formattable" if the expression uses a function that is not a formatting function.

BTW, after v45, this section needs to have some serious fixups to be much less vague about the terms "value" and "resolved value". Both are ambigously used, and it really matters for clarity.

I'd recommend changing almost all usages to the specific terms:

  • "resolved expression value"
  • "resolved variable value"
  • "resolved function value", and so on

Copy link
Collaborator

Choose a reason for hiding this comment

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

I'd recommend changing almost all usages to the specific terms:

* "resolved expression value"

* "resolved variable value"

* "resolved function value", and so on

This is what #645 addresses, not using quite the same terms, but I encourage you to comment there (at some point) if you want to suggest changes.

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks for the pointer, I'll look that over.

Copy link
Member

Choose a reason for hiding this comment

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

We're aware of the post-45 work.

The resolved value for a an expression does not have to be "formattable" if the expression uses a function that is not a formatting function.

Although I somewhat agree with you, I have always read "formatting" and "formattable" in this section to mean the processing found in this section--which include resolution, selection, and actual formatting. Formatting a message does not just mean making the output string.

Copy link
Member Author

Choose a reason for hiding this comment

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

Since we strongly distinguish between formatting functions and selection functions, I think it very likely that people will misunderstand that "formatting" means "formatting and selection" in this paragraph.

That being said, this could wait for v46.

1. if the function is a formatting function, it needs to be "formattable", i.e. it contains everything required by the eventual formatting.
2. if the function is a selection function, it needs to be "selectable", i.e. it contains everything required required by the eventual matching and ordering of keys.

The resolution of _text_ is rather straightforward,
and is detailed under _literal resolution_.
Expand Down Expand Up @@ -216,7 +217,7 @@ the following steps are taken:

4. Call the function implementation with the following arguments:

- The current _locale_.
- The current _formatting context_.
Copy link
Collaborator

Choose a reason for hiding this comment

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

This is too much, and potentially allows for too much "magic" in a custom function. I agree that the current text is missing the following:

  • base direction
  • bidi strategy
  • locale matcher strategy (not referenced in our current spec, but relevant at least for JS)

The full function context also includes e.g. all of the raw input values, and those should definitely not be made all ä available to all functions.

Copy link
Member

Choose a reason for hiding this comment

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

The formatting context might contain implemetation-specific goo (at Amazon we squirreled which site the user was on into field(s) in the context).

I agree that a badly behaved function might do Bad Magick. But I think it's useful to give developers access to what they need and stay out of their way after that. You'll note that I made the exact same suggestion recently (but changed it at your request, because it was not a parsimonious change at that moment in time).

Copy link
Member Author

Choose a reason for hiding this comment

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

And Stas and others want to be able to have access, like :u:function gender-agreement=$var.

locale is certainly wrong.

Copy link
Member

Choose a reason for hiding this comment

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

@macchiati

locale isn't wrong: one definitely wants that! However, I agree with you that more is needed.

The example :u:function gender-agreement=$var doesn't make sense to me, unless you mean for the gender agreement part to be implied?

Copy link
Member Author

Choose a reason for hiding this comment

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

I forget the exact example that Stas had, but it was to have options have values that are other variables, so that we could change the case (for example) of an adjective to match that of a noun.

Copy link
Member

Choose a reason for hiding this comment

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

Ah, I see what you're saying.

It's not the same thing. The variable in an option is, itself, subject to having its value resolved by the MF processor before the function is itself invoked (we say so in the options section). So it doesn't apply to needing the formatting context. The function gets the resolved value, not a variable reference.

- The resolved mapping of _options_.
- If the _expression_ includes an _operand_, its resolved value.

Expand Down