Document unicode math operators

[d-torrance]

We document the three unicode math operators that were added back in #3584 (·, ⊠, and ⧢).

We also:

• Add support for using the augmented versions of these operators.
• Add a Vector · Vector dot product method.

[pzinn]

I'm still opposed to this change, cf my rejected PR #3599

[mahrud]

I'm still opposed to this change, cf my rejected PR #3599

It wasn't rejected. We requested changes to balance introducing a new, useful feature while staying clear of undefined behavior when packages define conflicting keywords, at least until the details of that are ironed out. I think with relatively minor changes, it can still make it to this upcoming release.

[mahrud]

This looks awkward, and I'm not convinced that it is useful enough to justify supporting it.

[d-torrance]

My original thought was that every flexible binary operator (as long as it didn't introduce ambiguity when appending an extra =, like == -> ===) should support augmented assignment out of the box.

While it's certainly true it would probably be a bad idea to use ·= for an augmented dot product (First v is a vector, but after v ·= w, it's an element of the ring...), we might as well make it available for some other context where it might make sense.

[mahrud]

Since these paragraphs are mostly repeated, it may be worthwhile to have an automated section printed at the bottom of unicode operators that explains how to enter them. e.g. something like the "For the programmer" section underneath operators, which explains how to define methods on them.

Also, I still think every unicode operator should be tied to an ascii method name so it can be still used without unicode entry (e.g. ** and tensor for $\otimes$).

[d-torrance]

I like the idea of an automated section -- I'll push a proposal here in a bit.

As for the ascii method name... I'm not sure if we should force a particular name for each operator, or just leave it up to package authors. Maybe one package has ⊠ to be a shortcut for externalTensorProduct and another for strongProduct , etc.

But yeah, we should probably provide an ascii version for each method that's actually defined. I'll go ahead and add dotProduct(Vector, Vector) as a synonym for Vector · Vector.

[d-torrance]

I ended up dropping the Vector · Vector method from this PR, although I'll likely revisit it later. Various complications:

• What to do with rings over CC? We should probably use the Hermitian transpose, and perhaps that should be implemented in the engine rather than conjugating every entry one at a time?
• If we add a dotProduct method function to Core to serve as an ascii synonym, then we need to move the definition away from BoijSoiderberg, which currently exports it. But that that opens up a can of worms with the documentation, as its Inputs section defines five different inputs despite the fact that the method takes at most three inputs.

[mahrud]

• But that that opens up a can of worms with the documentation, as its Inputs section defines five different inputs despite the fact that the method takes at most three inputs.

For the record, the solution is to either use Synopsis or group the types together, e.g. M => {matrix,BettiTally} or similar.