fix: make compose do what it says

[thofma]

• First step at resolving compose(f,g) is inconsistent oscar-system/Oscar.jl#690
• Introduce a mandatory keyword argument for compose(f, g)
  and add a hint for f(g)/g(f) syntax.

[breaking]

Edit: I threw a dice and decided that

• compose(f, g; side = :right) means f(g),
• compose(g, f; side = :left) means g(f).

Obviously I don't have a strong opinion.

[codecov]

Codecov Report

Attention: 6 lines in your changes are missing coverage. Please review.

Comparison is base (a77cde7) 86.95% compared to head (f780751) 86.96%.
Report is 2 commits behind head on master.

Files	Patch %	Lines
src/AbsSeries.jl	71.42%	2 Missing ⚠️
src/Poly.jl	77.77%	2 Missing ⚠️
src/RelSeries.jl	71.42%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1606   +/-   ##
=======================================
  Coverage   86.95%   86.96%           
=======================================
  Files         115      114    -1     
  Lines       29628    29642   +14     
=======================================
+ Hits        25764    25778   +14     
  Misses       3864     3864           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[fingolfin]

So f(g) is "f evaluated at g", if I am not mistaken the resulting polynomial satisfies the condition f(g)(x) = f(g(x)) -- so $f(g) = f \circ g$ which is the function composition used for the nowadays customary notation for function application, and is a left action: $(f\circ g)(x) = f(g(x))$.

In contrast to the older, today unusual (outside of group theory and a few other special branches) notation for function application from the right: x^f= f(x), which is a right action: $(x^f)^g = x^{fg}$, where $fg:=g\circ f = g(f)$.

But I am not saying this should imply that the meaning of :left and :right for side should necessarily be switched: I don't think 99% of people reading this docstring would be able to come up with my reasoning and apply it within a sensible amount of time (that includes me -- I wouldn't dare to trust this, I would just do trial and error or look into the implementation or whatever)

Just to mention another alternative: I think Mohamed used PreCompose and PostCompose for these instead, in the context of morphisms. Granted, to me that still doesn't make it unique, but at least it give me a simple mnemonic ("Eselsbrücke") to remember it

PreCompose(f,g) produces a function which applies $f$ before (pre) $g$,
PostCompose(f,g) produces a function which applies $f$ after (post) $g$,

But this is for morphisms not polynomials and series, so we have at least one mental translation step, which could again go one way or the other...

Indeed, translated to polynomials and series one could say:

compose(f,g;side=:pre) (or side=:before) means "f before g", as in f(g)

or one could take the literal translation of Mohamed's definition, which would give the opposite:

compose(f,g;side=:pre) (or side=:before) means "f before g", as in g(f) because g(f(x)) applies f before g.

All in all I see no good way to define this. Maybe we should call it :a and :b then, it'd be at least short ;-).

Anyway, because of this: I have no particular motivation to disagree with your dice.

[thofma]

@fingolfin I renamed the keyword argument as we discussed it and will merge this soon.