clarify show doc strings

[JeffBezanson]

fixes #36072

[tkf]

It'd be nice if we could simply say

Suggested change

	property of `io`.
	property of `io` in `show(io::IO, ::MIME"text/plain", ::T)`.

However, current situation is complicated because

• non-vector arrays call 3-arg show and then fallback to 2-arg show, with :compact => true set.
• vectors do the same but without setting :compact => true.
• dictionaries and sets use 2-arg show.

Maybe it's better to be honest and say that there are some rough edges in show system with containers and there is no consistent way to control how items with custom items are shown. I do still think we should be using show(IOContext(io, :compact => true), "text/plain", element) consistently everywhere in 3-arg show of containers but it cannot block 1.5.

[JeffBezanson]

I'll try to reword this. We shouldn't think of it as controlling how your type is displayed inside a container --- that can never fully work, because it will always depend on what the container does. All you really need to know is "MIME type = human readable, 2-arg = parseable, compact = keep it short". For example, matrices call 3-arg show because they are themselves using a human-readable output format. But if some other container only has a parseable representation, then its elements will use 2-arg show.

[tkf]

All you really need to know is "MIME type = human readable, 2-arg = parseable, compact = keep it short".

Yes, that's the ideal situation. It'd be great if we can orthogonalize target reader ("machines" vs humans) and the compactness of the output. The reason why I suggested to add "in show(io::IO, ::MIME"text/plain", ::T)" was that I thought this paragraph was about human-readable format (as that's how it starts).

[tkf]

Thanks for documenting this.