Tag Optional as an operator...

[rocky]

And correct the name OptionAL, not Option.

[mmatera]

Not sure if this symbol can be understood as an operator. In the first place, it can only accept a very special kind of elements as operands. I do not see clear how precedence an associativity must be assigned, and it would be a Postfix or Infix operator depending on the context.

[rocky]

Not sure if this symbol can be understood as an operator.

All of the features below that concern you can be found in other WMA operators.

In the first place, it can only accept a very special kind of elements as operands.

That's true of most of the other operators as well. And it is true of most Builtin functions; an operator is just a shorthand for a built-in function. In fact its the other way around: most operators and functions place limits on their parameters or operands.

For example, Integral takes two parameters: an expression and a partial. Even the most common operators, Times and Plus, have limitations on their operands: they must be numeric.

I do not see clear how precedence an[d] associativity must be assigned,

Actually, we just came across an example of this. Pattern and Optional, which both use the character ":" as their operator symbol, bind Optional before Pattern. So Pattern has precedence 150 while Optional has precedence 140.

If two patterns can be juxtaposed next to one another, then there definitely is an associativity. If they can't ever be juxtaposed, then the associativity is "null" or "unkown" (used in the case of Box operators). See, for example, the Information operator.

and it would be a Postfix or Infix operator depending on the context.

This kind of thing also happens in other operator symbols; -- and ++ are both operator symbols that can appear before or after an expression. And even the common + and - operators can be used in both unary and binary forms depending on the context.

Note that in the YAML table, though, these appear with different names. So we have Predecrement as the operator name when -- appears before an expression and PostDecrement as the operator name when it appears afterwards. Same with disambiguating +: UnaryPlus versus Plus.

In sum, WMA defines a lot of operators. More than most people might expect. But that's not surprising. WMA pushes language concepts to extreme limits. Just as there are a lot more operators than found in any other common programming language I know, there are a lot more built-in functions in the language as well. While this kind of thing is a bit unusual, it is not illogical.

[mmatera]

The particularity of this Optional operator is that it has different notations for one and two operators.

Other operators have other particularities: Integrate involves two operator characters (\[Integral] and \[DifferentialD]), Times uses different operators in StandardForm and OutputForm, and -- can be interpreted different as Prefix and Postfix operators. Also WMA reports for Precedence[Optional] a value 140, which is not the default value (670). The same happens with Blank, which has a precedence of 730, but I am not sure if we treat it as an operator.

In any case, my goal now is to complete the implementation of a framework for MakeBoxes evaluation, with a behavior closer to WMA. It would be nice if it is possible to DRY the implementation of Optional and other symbols using the existing interface, but I do not think it is central.
Regarding the user documentation, the question is whether it is clear enough for the user be able to use and understand it. I added some examples of formatting to include some doctests, but these doctests could be included in the format_test.yaml file.

[mmatera]

Said this, I think the change in the entry does not cause any harm, and makes the table more accurate, so LGTM.

[rocky]

The particularity of this Optional operator is that it has different notations for one and two operators.

Other operators have other particularities: Integrate involves two operator characters (\[Integral] and \[DifferentialD]),

Don't confuse operator characters like \[Integral] with the operators like Integrate. (In some cases, like DoubleContourIntegral there is both a character name as well as an operator with the same name. So, it can lead to confusion)

Times uses different operators in StandardForm and OutputForm, and -- can be interpreted different as Prefix and Postfix operators. Also WMA reports for Precedence[Optional] a value 140, which is not the default value (670). The same happens with Blank, which has a precedence of 730, but I am not sure if we treat it as an operator.

In any case, my goal now is to complete the implementation of a framework for MakeBoxes evaluation, with a behavior closer to WMA. It would be nice if it is possible to DRY the implementation of Optional and other symbols using the existing interface, but I do not think it is central.

This is not just about reducing the size of the code. More important is the understanding of the principles of how things are organized, which by its very nature leads to a more compact implementation. In WMA, right or wrong, there is a lot that is pushed or framed in terms of operators and operator precedence. This generally dictates how things work.

As an analogy, one could write some code saying that when I see 612 + 300, it has the same value as 912. And I might notice a pattern for what happens when I see + 300. And I might call that DRYing or reducing the size of code. But what this misses is that the concept of how addition works, which is driving the implementation.

Understanding and following the concept is more likely to predict and produce more correct results, assuming that's what WMA is doing. (And I think it works this way.)

Regarding the user documentation, the question is whether it is clear enough for the user be able to use and understand it. I added some examples of formatting to include some doctests, but these doctests could be included in the format_test.yaml file.

When I read the description that was in the master branch, the two problems I had were spending a lot of mental effort trying to understand the example, as well as what idea was being conveyed. Part of this is was a lack of description of intent. Part of it was adding extraneous aspects, and part of the difficulty was in using examples involving something other than what was being conveyed.

And then in the rewrite, I realized that there were some fundamental concepts like the notion that Pattern and Optional are operators, and they happen to use the same operator symbol, ":".

So instead of describing how to disambiguate a particular expression as an isolated fact, it becomes showing how to apply the standard rules when two operators (which happen to use the same operator symbol) are juxtaposed.