clarifications on display vs show (#24513)

From the [mailing list](https://discourse.julialang.org/t/output-like-print/6930/7?u=stevengj)

(cherry picked from commit 3077732)

base/multimedia.jl

@@ -187,6 +187,30 @@ end
 
 xdisplayable(D::Display, args...) = applicable(display, D, args...)
 
+"""
+ display(x)
+ display(d::Display, x)
+ display(mime, x)
+ display(d::Display, mime, x)
+
+Display `x` using the topmost applicable display in the display stack, typically using the
+richest supported multimedia output for `x`, with plain-text [`STDOUT`](@ref) output as a fallback.
+The `display(d, x)` variant attempts to display `x` on the given display `d` only, throwing
+a [`MethodError`](@ref) if `d` cannot display objects of this type.
+
+In general, you cannot assume that `display` output goes to `STDOUT` (unlike [`print(x)`](@ref) or
+[`show(x)`](@ref)). For example, `display(x)` may open up a separate window with an image.
+`display(x)` means "show `x` in the best way you can for the current output device(s)."
+If you want REPL-like text output that is guaranteed to go to `STDOUT`, use
+[`show(STDOUT, "text/plain", x)`](@ref) instead.
+
+There are also two variants with a `mime` argument (a MIME type string, such as
+`"image/png"`), which attempt to display `x` using the requested MIME type *only*, throwing
+a `MethodError` if this type is not supported by either the display(s) or by `x`. With these
+variants, one can also supply the "raw" data in the requested MIME type by passing
+`x::AbstractString` (for MIME types with text-based storage, such as text/html or
+application/postscript) or `x::Vector{UInt8}` (for binary MIME types).
+"""
 function display(x)
  for i = length(displays):-1:1
  if xdisplayable(displays[i], x)