Re: Documentation by function beyond elisp

[Eshel Yaron <me@eshelyaron.com>]

Augusto Stoffel <arstoffel@gmail.com> writes:

> On Fri, 10 Mar 2023 at 16:50, Eshel Yaron wrote:
>
>> IMO ElDoc and Help and two pretty different features, each with its own
>> use and purpose.
>> Eglot integrates with ElDoc but not with Help AFAIU,
>
> Right, the LSP protocol doesn't have an interface for anything like
> `C-h o'.  You only get information on the symbol at point.

Seems so, that strikes me as an unfortunate limitation of the protocol
as language servers are surely in a good position to provide this
information.

>> but language-specific packages can (and should!) integrate with both of
>> these facilities.  Emacs lets package authors reuse the Help UI pretty
>> easily.  For example, my package sweeprolog.el (for working with
>> SWI-Prolog code) provides both ElDoc integration and a command
>> sweeprolog-describe-predicate that works much like describe-predicate,
>> it uses the help.el interface to show a proper *Help* buffer with the
>> documentation of a given Prolog predicate.
>
> The generic Emacs way to provide this functionality is the Info symbol
> lookup command `C-h S'.

I'm not sure I agree that Info and similar manuals solve the same
problem as *Help* buffers.  During development I think that Help is much
more useful, as its aware of the current state of your project and
environment.  One obvious benefit is the ability to jump to the source
code corresponding to what you're getting help for with `s`.

> If your language doesn't have an Info manual you may have better luck
> with the `devdocs' package (which I mention as a shameless but
> pertinent plug).

Great stuff :) I actually just installed devdocs a few days ago to
access the PostgreSQL docs and it worked very well.

> Out of curiosity: apart from the issue of availability of documentation
> in different formats, is there any prolog-specific logic in
> sweeprolog-describe-predicate?

Some, yes.  Basically it uses SWI-Prolog's own documentation system to
get the current documentation for the given predicate in HTML format,
then it uses SHR with some custom shr-external-rendering-functions to
create nicely formatted text for the *Help* buffer.  That's the gist of
it.  It also links to the source location of the predicate and lists
some properties of the predicate like whether its exported or not.