Documentation for quotient rings (residue rings)

[JohnAAbbott]

Describe the bug
There are (at least) two descriptions of quo. The descriptions about the returned map are
inconsistent (see attached screenshots). One description agrees with my experiments:
namely the map returned (as 2nd value) is the canonical quotient R -> R/I;
unfortunately searching for quotient ring in the help search window leads first to the
other entry.

To Reproduce
Go to the latest documentation: https://docs.oscar-system.org/stable/
Enter quotient ring in the search box. And click on first supplied link:
[Quotient Rings](https://docs.oscar-system.org/stable/Hecke/orders/ideals/#Quotient-Rings) (section, Ideals)

Expected behavior
Perhaps make the link to Generic residue rings appear closer to the top of the list of
offered links. I note that there is also a link to Residue rings (from Nemo). The links
could give more information about the contexts in which they are relevant.

System (please complete the following information):
I refer to the documentation at the link given above (on 2023-02-08). And the Oscar
version I tried is:

Screenshot 1

Screenshot 2

Screenshot 3

julia> Oscar.versioninfo(full=true)
OSCAR version 0.11.2
  combining:
    AbstractAlgebra.jl   v0.27.8
    GAP.jl               v0.9.3
    Hecke.jl             v0.16.10
    Nemo.jl              v0.32.7
    Polymake.jl          v0.8.3
    Singular.jl          v0.14.0
  building on:
    Antic_jll               v0.201.500+0
    Arb_jll                 v200.2300.0+0
    Calcium_jll             v0.401.100+0
    FLINT_jll               v200.900.4+0
    GAP_jll                 v400.1200.200+0
    Singular_jll            v403.101.500+0
    libpolymake_julia_jll   v0.8.3+1
    libsingular_julia_jll   v0.27.0+1
    polymake_jll            v400.700.1+1
See `]st -m` for a full list of dependencies.

Julia Version 1.8.5
Commit 17cfb8e65ea (2023-01-08 06:45 UTC)
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 20 × Intel(R) Core(TM) i9-10900 CPU @ 2.80GHz
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, skylake)
  Threads: 1 on 20 virtual cores
Official https://julialang.org/ release

Additional context
Add any other context about the problem here.

[JohnAAbbott]

Sorry. It seems to have merged the 3 screenshots into a single large image. I hope it is nonetheless comprehensible.

[fingolfin]

This is in the end a problem with the search tool used by Documenter.jl, not sure we can do much about it at this point, but then again I asked @aaruni96 to look a bit into this some time ago, but he essentially did run into a brick wall :-/.

We could try to talk to the Documenter people again, but in the end, we may either have to assign/hire someone to work on it, switch to a different documentation system (difficult at this point...) or live with it.

A related search problem is searching for quo which lists tons and tons of hits; then try to find the one for e.g. MPolyRing. good luck

[fingolfin]

Upon revisiting this, I now realize that there are really two separate issues reported here:

1. an issue with the search in our documentation (we are painfully aware of its deficiencies)
2. an issue were the Hecke method quo(O::AlgAssAbsOrd, I::AlgAssAbsOrdIdl) returns a map $O/I\to O$ which is unlike most other quo methods which would return a map-with-section $O \to O/I$.

The second point is perhaps something for @fieker and @thofma to ponder. It's probably too late to change that, but perhaps there could be a warning in the docstring that this breaks the usual API?

[fingolfin]

@fieker says this is a bug in the docstring, which then should be fixed.

Once that is done I think we can close this in favor of issue #3816

[lgoettgens]

@fieker says this is a bug in the docstring, which then should be fixed.

Once that is done I think we can close this in favor of issue #3816

@fieker @thofma could you fix the docstring in Hecke?

[HereAround]

@fieker and @thofma was the docstring fixed in Hecke?

[fingolfin]

triage looked a this, @fieker will check and take care of it

[fingolfin]

I just had a look at the code and the method indeed seems fine, "just" the docstring needs to be fixed. Proof of work:

julia> Qx, x = polynomial_ring(QQ, "x");

julia> K1, a1 = number_field(x^3 - 2, "a");

julia> O1 = EquationOrder(K1, true);

julia> typeof(O1)   # verify this is the right type
AbsSimpleNumFieldOrder (alias for AbsNumFieldOrder{AbsSimpleNumField, AbsSimpleNumFieldElem})

julia> pis = prime_ideals_over(O1, 5);

julia> R, phi = quo(O1, pis[1]);

julia> typeof(phi)
Hecke.AbsOrdQuoMap{AbsSimpleNumFieldOrder, AbsSimpleNumFieldOrderIdeal, AbsSimpleNumFieldOrderElem}

julia> domain(phi) == O1
true

julia> codomain(phi) == R
true

If @fieker and @thofma are busy, perhaps @JohnAAbbott (who reported this) can adjust the docstring?