Add hint for eliminate using a proper subring

[thofma]

• remove code duplication for detecting morphisms that map generators to generators
• expand the note in the eliminate docstring to point to preimage
• add an explicit example to the docstring

CC: @fieker

Probably closes #2590.

The docstring is expanded by adding the following example:

julia> R, (t, x, y, z) = polynomial_ring(QQ, [:t, :x, :y, :z]);

julia> I = ideal(R, [t-x, t^2-y, t^3-z])
Ideal generated by
  t - x
  t^2 - y
  t^3 - z

julia> TC = eliminate(I, A)
Ideal generated by
  -x*z + y^2
  x*y - z
  x^2 - y

julia> eliminate(I, lex(R), 2)
Ideal generated by
  y^3 - z^2

julia> base_ring(TC)
Multivariate polynomial ring in 4 variables t, x, y, z
  over rational field

# New stuff:
julia> S, (yy, zz) = QQ[:yy, :zz]; # Construct the elimination as an ideal of S

julia> f = hom(S, R, [y, z]);

julia> TCS = preimage(f, I)
Ideal generated by
  yy^3 - zz^2

julia> base_ring(TCS)
Multivariate polynomial ring in 2 variables yy, zz
  over rational field

[HechtiDerLachs]

Thank you for the cleanup!

This PR streamlines the use of _maps_variables_to_variables with the previous ad hoc implementations of the same functionality in the constructor of maps.

[HechtiDerLachs]

In the previous implementation this field being unassigned was the indicator that the map does not take variables into variables. Now it seems that the field is assigned by default. But I suppose you deliberately changed the overall concept here and took that into account, right?

Either way: I was just a bit puzzled that this field is assigned only if a specific kwarg is set to true.

[thofma]

1. Yes, I changed the concept so that there is now only one way to ask whether variables map to variables. Before there were two: Either call _maps_variables_to_variables or check isdefined(f, ...).
2. The part with always setting the field is on purpose. Repeatedly constructing Int[] is expensive. Now one should never query isdefined(f, :) directly, but just ask whether _maps_... is true.
3. The special kwarg was added by you. I am happy to remove it, since it is never used and cannot be used legally using hom, see Speed up polynomial mappings #4124 (comment).

[HechtiDerLachs]

I see. I think at the time I wanted to leave some backdoor open to avoid the check. That's why I introduced the kwarg, but did not yet forward it to the user-facing constructors. If it does not conflict with your implementation, then I would say: let's just keep it.

Not relying on isdefined anymore makes sense. This was a bit opaque, anyway.

[thofma]

OK, let's keep keeping it. Thanks for the review.

[fieker]

if this helps, I'm happy. Avoiding GB is always good