bug#47109: eldoc.el: Allow custom separator between documentations in the echo area

[João Távora]

Thank you both,

Personally, I'm fine with the first whitespace patch, as long as it's
only whitespace.

I've had a look at the simple second patch and while such a thing is
indeed mostly innocuous (and potentially very useful), I wonder if we
shouldn't be a bit more ambitious.

There are bound to be many more sophisticated strategies for composing
items of documentation and it doesn't make sense, to me, for Eldoc to
add two new user-visible endpoints to what is already a long,
ad-hoc-tailored list of legacy endpoints just for the relatively limited
technique of "composition by concatenation".

For example, in elisp-mode, one plan could be have the composition of
the multiple documentation items collected by the elisp eldoc backends
resultin a documentation buffer that looks very much like what you get
from describe-symbol or C-h o in form, function and content.  That
potentially needs a much more sophisticated composition strategy that is
specific to the elisp-mode major mode.

So I'd argue for a a new eldoc-render-documentation function.

That should give the user enough freedom to do these basic separators
but doesn't bloat the API with limited micro-switches (at least not yet,
we can add such things in the main eldoc.el eventually).

eldoc-render-documentation could be a generic function given:

- the items of documentation to render

- the target "canvas", which may be a buffer (the eldoc buffer), the echo
  area, or some other object (a tooltip? some user-defined documentation
  container?)

It should output things in a buffer, or maybe a string.

There seems be bit of an overlap here with `eldoc-display-functions',
but it is rather a healthy relation, in my view.  Those functions should
be more concerned with managing access and visibility of the target
canvas than actually rendering the text, which may be specific to a
major-mode and a potentially orthogonal task.

So each element in `eldoc-display-functions` should call
`eldoc-render-documentation` passing it suitable arguments to produce
the final text.

João