Update selection-declaration design doc based on mtg / issue discussion

[echeran]

Updates design doc prompted by meeting discussions as well as #824 comments.

[aphillips]

This might be clearer if we show separate annotation?

.input {$person :personName}
.match {$person :gender}
male {{Does {$person} print 'male' or the person's name?}}
* {{This example is the same as use case 6}}

... or is that not your intention?

[mihnita]

I don't find this to be clear.
It is in fact what we have today.

And depending on the mental model of the reader, it is unclear if the {$person} inside the message is the :gender one or the :personName one.

It is in fact what started the issue, that I can do stuff like this:

.input {$count :integer}
.match {$count :number minFractionalDigits=2}
 ...

For clarity I can imagine two options:

1. One has a declare a .local, which gives us a different name:

.local $theName = {$person :personName}
.match {$person :gender}
male {{Does {$theName} print 'male' or the person's name?}}
* {{This example is the same as use case 6}}

OR

2. The .match cannot have any function / parameters

.input {$person :personName}
.match {$person}
male {{Does {$person} print 'male' or the person's name?}}
* {{This example is the same as use case 6}}

Case 2 would not be useful in this case, with gender, but would be when we want consistency, in plural

[mihnita]

---

We already decided for immutability in .local and .input
WDYT about thinking of .match also as some kind of immutable?

These would be the rules:

if .match on $foo has any function / attributes / options on it
    if there was a .local $foo = {...} or .input {$foo ...} before
        ERROR
    else
        $foo is "bound" to the function / attributes / options in .match for the rest of the message
        // This gives us consistency between the :number selection / formatting
else
    if there was a .local $foo = {...} or .input {$foo ...} before, with a function on it
        use that exact definition ("binding") to do the selection // What we do today
    else
        ERROR, because the items on which we select must always have a function
        // So that we know what we select on, what keys might be valid, etc.
        // This is something we agreed a long time ago, useful for both linting, L10N tools, and human translators

[mihnita]

Exercising the idea above:

---

.input {$person :name}
.match {$person :gender}

=> ERROR.
$person is "bound" to two different types / transforms / functions
Or .match tries to change an immutable .input, if you want to think of it in terms of immutability

---

.local $personName = {$person :name}
.match {$person :gender}
   .... {Here we can use both {$personName} and {$person} (second one kind of useless, but clear) }

=> CORRECT
We have two "variables", personName and person, no conflicts, everything is clear

---

.match {$count :number minFractionalDigits=2}
   .... {Here we can use {$count} and it means it is formatted as described in .match, good}

CORRECT

---

.input {$count :number minFractionalDigits=2}
.match {$count}
   .... {Here we can use {$count} and it means it is formatted as described in .match, good}

CORRECT

---

.input {$count :number minFractionalDigits=2}
.match {$count :number}
   .... {Here we can use {$count} and it means it is formatted as described in .match, good}

ERROR
Even if the function name is the same, it is still confusing.
Is .match {$count :number} inheriting the options from .input or not?

[echeran]

My intention is to highlight that selection and formatting may require different functions. My example accomplishes that straightforwardly without getting into tangential questions about function composition, tradeoffs of concision vs. simplicity, etc.

I was initially confused by your example, even though it's more concise, because it wasn't making sense to me. If .input is binding the value of the expression {$person :personName} back to $person, then we no longer have the full person object accessible to provide to the :gender function in the subsequent line performing selection: .match {$person :gender}. Am I reading that right? If so, that of course highlights the outstanding question of how we should define function composition, but that's a separate topic.

Also, the example might engender the reader to want to declare a .local person-name {$person :personName} for all the repetition in the patterns, but then if they do, they would realize that such refactoring is independent of selection. So the idea of requiring selection to take place only on variables (the design doc alternative named "Match on variables instead of expressions"), which in turn would require a .local declaration for the selector expression {$person :gender}, would not buy us anything in terms of consistency within the message because there was never a linkage between the selector expression function and pattern placeholder formatting function.

[bearfriend]

@mihnita Having read your logic and explanation, it makes sense and I personally wouldn't mind this sort of conditional mutability, but as I've stated elsewhere I just see this as overly complicated and most developers are not going to invest the time to fully grasp what will happen under these different conditions, which ultimately just trades slightly increasing flexibility and conciseness for much more confusion and errors.

I think something more rigid like "selection never mutates" is incredibly clear, and barely harms the experience, if at all. You can repeat your expressions or use an input/ local.

[aphillips]

Note that this discussion is about text that @echeran is helpfully suggesting in the design document... a document that, I'll point out, talks about all of the issues on this thread and whose point is to illustrate choices we might make to resolve the problems it raises. @echeran has answered my question, so I'm happy to merge this so that we can have the actual discussion 😄

[macchiati]

I can think of one slightly modified option

Much of objection to the 'mutating by match' option seems to be caused by the somewhat unusual case with two selectors on the same variable.

.match {$num ..x..}{$num ..y..}
a b {{which {$num} is it?}}

I think think of two options to address that.

Option 1. Forbid two of the same variables in the same .match.

That is, the above example would need to be reworked to:

.local $num2 {$num}
.match {$num ..x..}{$num2 ..y..}
a b {{It is the second, {$num2}.}}

or the equivalent

.local $num2 {$num ..y..}
.match {$num ..x..}{$num2}
a b {{It is the second, {$num2}.}}

Option 2. A slight amendment to "Provide a #-like Feature"

If you have two identical variables in the match statement, use _N to distinguish.

.match {$num ..x..}{$num ..y..}
a b {{It is the second, {$num_2}.}}

[echeran]

Responding to what @macchiati said:

Much of objection to the 'mutating by match' option seems to be caused by the somewhat unusual case with two selectors on the same variable.

.match {$num ..x..}{$num ..y..} a b {{which {$num} is it?}}

I disagree; I think the crux of the matter is actually about how we treat the formatting/transformation for selection as compared to the formatting for display of placeholders in a pattern. Are these things the same or not?

See my comment in the parent PR in which I describe the undesirable complexities introduced by the various proposed options as a consequence of their attempts to create concision in support of the cases when -- or require declarations that always assert & enforce -- the idea that formatting for selection and formatting for display are the same. I assert that they're not the same, and this PR is providing another counter example to the design doc, and calling out the strong concerns of complexity mentioned by others in issues and the meeting.

[macchiati]

I don't think anyone is saying that selection should be literally based on the formatted string (that seems to be what you are saying by "formatting for selection and formatting for display are the same"). What I'm saying is that selection should be consonant with the formatted string — for functions that are both selectors and formatters.

What constitutes "consonant with" will vary according to the function. For :number, that means that the digits and decimal position within them are mapped to either a plural category or an ASCII literal (compact numbers and scientific notation are slightly different; I won't go into that here).

[echeran]

re: @macchiati

I don't think anyone is saying that selection should be literally based on the formatted string (that seems to be what you are saying by "formatting for selection and formatting for display are the same").

That's not what I am saying overall, although yes that particular sentence was unclear and misleading because I was too terse. The point I was making in the parent PR comment is that the design of the alternatives in the design doc lean in that direction -- either they are designed for or are inspired to better support cases where the function is the same and the options are similar. Hopefully I spilled enough words for clarity there.

What I'm saying is that selection should be consonant with the formatted string — for functions that are both selectors and formatters. What constitutes "consonant with" will vary according to the function.

Right, and I agree that there is a level of nuance to the situation that needs to be considered as we decide things. My concern is how much complexity the design doc's alternatives would add to the mental model needed to make sense of a message, and that's separate from the question of how well those designs would support cases where the selection function & display formatting function differ.