Documentation by function beyond elisp

Documentation by function beyond elisp

[goncholden]

[-- Attachment #1: Type: text/plain, Size: 293 bytes --]

For elisp files, emacs has the capability of showing documentation by function. A valuable tool
would be to extend such functionality to others like bash and awk. Perhaps one can come up
with something that could work beautifully. Have there been an ideas for such capability extension
before?

[-- Attachment #2: Type: text/html, Size: 805 bytes --]

Re: Documentation by function beyond elisp

[Po Lu]

goncholden <goncholden@protonmail.com> writes:

> For elisp files, emacs has the capability of showing documentation by function.  A valuable tool
> would be to extend such functionality to others like bash and awk.  Perhaps one can come up 
> with something that could work beautifully.  Have there been an ideas for such capability extension
> before?

Both the Bash and Awk manuals can be read inside Info.

Re: Documentation by function beyond elisp

[goncholden]

------- Original Message -------
On Friday, March 10th, 2023 at 12:07 AM, Po Lu <luangruo@yahoo.com> wrote:


> goncholden goncholden@protonmail.com writes:
> 
> > For elisp files, emacs has the capability of showing documentation by function. A valuable tool
> > would be to extend such functionality to others like bash and awk. Perhaps one can come up
> > with something that could work beautifully. Have there been an ideas for such capability extension
> > before?
> 
> 
> Both the Bash and Awk manuals can be read inside Info.

The capability is focused upon documenting user-defined functions in bash and awk files.

Re: Documentation by function beyond elisp

[Po Lu]

goncholden <goncholden@protonmail.com> writes:

> The capability is focused upon documenting user-defined functions in
> bash and awk files.

If you write a manual for your shell macros, functions, or awk
functions, you can read it in Info as well.  The same applies to other
languages such as C.  So please, what exactly is the feature you want?

For an extensive example of the former, see the Autoconf manual.

Thanks.

Re: Documentation by function beyond elisp

[goncholden]

------- Original Message -------
On Friday, March 10th, 2023 at 1:33 AM, Po Lu <luangruo@yahoo.com> wrote:


> goncholden goncholden@protonmail.com writes:
> 
> > The capability is focused upon documenting user-defined functions in
> > bash and awk files.
> 
> 
> If you write a manual for your shell macros, functions, or awk
> functions, you can read it in Info as well. The same applies to other
> languages such as C. So please, what exactly is the feature you want?
> 
> For an extensive example of the former, see the Autoconf manual.
> 
> Thanks.

Your suggestion is then to write a manual to document functions and use info
for display.  I have been scrutinising the possibility that the documentation
information is taken directly from the source files, rather than having to write
a separate thing, closely resembling what happens with elisp user-defined functions.

Re: Documentation by function beyond elisp

[Eli Zaretskii]

> Date: Thu, 09 Mar 2023 11:33:02 +0000
> From: goncholden <goncholden@protonmail.com>
> 
> For elisp files, emacs has the capability of showing documentation by function.  A valuable tool
> would be to extend such functionality to others like bash and awk.  Perhaps one can come up 
> with something that could work beautifully.  Have there been an ideas for such capability extension
> before?

Did you try "C-h S"?

Re: Documentation by function beyond elisp

[goncholden]

------- Original Message -------
On Friday, March 10th, 2023 at 12:24 AM, Eli Zaretskii <eliz@gnu.org> wrote:


> > Date: Thu, 09 Mar 2023 11:33:02 +0000
> > From: goncholden goncholden@protonmail.com
> > 
> > For elisp files, emacs has the capability of showing documentation by function. A valuable tool
> > would be to extend such functionality to others like bash and awk. Perhaps one can come up
> > with something that could work beautifully. Have there been an ideas for such capability extension
> > before?
> 
> 
> Did you try "C-h S"?

That does not work for user-defined awk functions, complaining that a function name
is not a symbol.

Re: Documentation by function beyond elisp

[Eli Zaretskii]

> Date: Thu, 09 Mar 2023 13:01:31 +0000
> From: goncholden <goncholden@protonmail.com>
> Cc: emacs-devel@gnu.org
> 
> > > For elisp files, emacs has the capability of showing documentation by function. A valuable tool
> > > would be to extend such functionality to others like bash and awk. Perhaps one can come up
> > > with something that could work beautifully. Have there been an ideas for such capability extension
> > > before?
> > 
> > 
> > Did you try "C-h S"?
> 
> That does not work for user-defined awk functions, complaining that a function name
> is not a symbol.

That's true.  But you never said anything about user-defined in your
OP...

Re: Documentation by function beyond elisp

[goncholden]

------- Original Message -------
On Friday, March 10th, 2023 at 3:29 AM, Eli Zaretskii <eliz@gnu.org> wrote:


> > Date: Thu, 09 Mar 2023 13:01:31 +0000
> > From: goncholden goncholden@protonmail.com
> > Cc: emacs-devel@gnu.org
> > 
> > > > For elisp files, emacs has the capability of showing documentation by function. A valuable tool
> > > > would be to extend such functionality to others like bash and awk. Perhaps one can come up
> > > > with something that could work beautifully. Have there been an ideas for such capability extension
> > > > before?
> > > 
> > > Did you try "C-h S"?
> > 
> > That does not work for user-defined awk functions, complaining that a function name
> > is not a symbol.
> 
> 
> That's true. But you never said anything about user-defined in your
> OP...

Am now more specific then, because for elisp files it is understood that
documentation strings relate beyond the built-in functions.

Re: Documentation by function beyond elisp

[Eli Zaretskii]

> Date: Thu, 09 Mar 2023 13:01:31 +0000
> From: goncholden <goncholden@protonmail.com>
> Cc: emacs-devel@gnu.org
> 
> 
> ------- Original Message -------
> On Friday, March 10th, 2023 at 12:24 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> 
> > > Date: Thu, 09 Mar 2023 11:33:02 +0000
> > > From: goncholden goncholden@protonmail.com
> > > 
> > > For elisp files, emacs has the capability of showing documentation by function. A valuable tool
> > > would be to extend such functionality to others like bash and awk. Perhaps one can come up
> > > with something that could work beautifully. Have there been an ideas for such capability extension
> > > before?
> > 
> > 
> > Did you try "C-h S"?
> 
> That does not work for user-defined awk functions, complaining that a function name
> is not a symbol.

You could teach etags about Awk programs and shell scripts.  Or maybe
some variant of the tags program out there already supports those, in
which case Emacs should be able to give you what you want for free,
after you run that tags program on your Awk/Bash source files.

Re: Documentation by function beyond elisp

[goncholden]

------- Original Message -------
On Friday, March 10th, 2023 at 3:48 AM, Eli Zaretskii <eliz@gnu.org> wrote:


> > Date: Thu, 09 Mar 2023 13:01:31 +0000
> > From: goncholden goncholden@protonmail.com
> > Cc: emacs-devel@gnu.org
> > 
> > ------- Original Message -------
> > On Friday, March 10th, 2023 at 12:24 AM, Eli Zaretskii eliz@gnu.org wrote:
> > 
> > > > Date: Thu, 09 Mar 2023 11:33:02 +0000
> > > > From: goncholden goncholden@protonmail.com
> > > > 
> > > > For elisp files, emacs has the capability of showing documentation by function. A valuable tool
> > > > would be to extend such functionality to others like bash and awk. Perhaps one can come up
> > > > with something that could work beautifully. Have there been an ideas for such capability extension
> > > > before?
> > > 
> > > Did you try "C-h S"?
> > 
> > That does not work for user-defined awk functions, complaining that a function name
> > is not a symbol.
> 
> 
> You could teach etags about Awk programs and shell scripts. Or maybe
> some variant of the tags program out there already supports those, in
> which case Emacs should be able to give you what you want for free,
> after you run that tags program on your Awk/Bash source files.

etags are all new for me.

Re: Documentation by function beyond elisp

[Eli Zaretskii]

> Date: Thu, 09 Mar 2023 17:04:55 +0000
> From: goncholden <goncholden@protonmail.com>
> Cc: emacs-devel@gnu.org
> 
> > You could teach etags about Awk programs and shell scripts. Or maybe
> > some variant of the tags program out there already supports those, in
> > which case Emacs should be able to give you what you want for free,
> > after you run that tags program on your Awk/Bash source files.
> 
> etags are all new for me.

All the languages except Emacs Lisp are supported via etags.  And you
can optionally have Emacs Lisp functions supported by etags as well,
in which case you will be able to find functions that are not yet
loaded into Emacs.

Re: Documentation by function beyond elisp

[Yuri Khan]

On Thu, 9 Mar 2023 at 19:00, goncholden <goncholden@protonmail.com> wrote:

> For elisp files, emacs has the capability of showing documentation by function.  A valuable tool
> would be to extend such functionality to others like bash and awk.  Perhaps one can come up
> with something that could work beautifully.  Have there been an ideas for such capability extension
> before?

For languages other than Elisp, this is handled by the language
server. Eglot arranges for language-server-provided function help to
be displayed by ElDoc.

Re: Documentation by function beyond elisp

[Ihor Radchenko]

Yuri Khan <yuri.v.khan@gmail.com> writes:

> For languages other than Elisp, this is handled by the language
> server. Eglot arranges for language-server-provided function help to
> be displayed by ElDoc.

What about an equivalent of the *Help* buffer?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Documentation by function beyond elisp

[Yuri Khan]

On Fri, 10 Mar 2023 at 16:12, Ihor Radchenko <yantar92@posteo.net> wrote:
>
> Yuri Khan <yuri.v.khan@gmail.com> writes:
>
> > For languages other than Elisp, this is handled by the language
> > server. Eglot arranges for language-server-provided function help to
> > be displayed by ElDoc.
>
> What about an equivalent of the *Help* buffer?

Well, what about it? You move the point to an identifier. Its
signature and a few lines of documentation are shown in the echo area.
You invoke (eldoc-doc-buffer) and see the whole documentation.

It may be a bit inconvenient that the content of that buffer changes
as you move point to a different identifier. But that can be worked
around with (clone-buffer).

Re: Documentation by function beyond elisp

[João Távora]

On Fri, Mar 10, 2023 at 10:24 AM Yuri Khan <yuri.v.khan@gmail.com> wrote:
>
> On Fri, 10 Mar 2023 at 16:12, Ihor Radchenko <yantar92@posteo.net> wrote:
> >
> > Yuri Khan <yuri.v.khan@gmail.com> writes:
> >
> > > For languages other than Elisp, this is handled by the language
> > > server. Eglot arranges for language-server-provided function help to
> > > be displayed by ElDoc.
> >
> > What about an equivalent of the *Help* buffer?
>
> Well, what about it? You move the point to an identifier. Its
> signature and a few lines of documentation are shown in the echo area.
> You invoke (eldoc-doc-buffer) and see the whole documentation.
>
> It may be a bit inconvenient that the content of that buffer changes
> as you move point to a different identifier. But that can be worked
> around with (clone-buffer).

That's true.  I'm working on some changes (will soon open a separate
bug for it), so that each member of 'eldoc-display-functions' uses its
own "outlet" (buffer, child frame, echo-area) independently, which is
not the case.  This should also allow users to obtain a buffer that is
"pinned" when they interactively invoke M-x eldoc.  That pinned buffer
should be "an equivalent of the *Help* buffer" for all (or most)
intents and purposes.

João

Re: Documentation by function beyond elisp

[Eshel Yaron]

Yuri Khan <yuri.v.khan@gmail.com> writes:

> On Fri, 10 Mar 2023 at 16:12, Ihor Radchenko <yantar92@posteo.net> wrote:
>>
>> Yuri Khan <yuri.v.khan@gmail.com> writes:
>>
>> > For languages other than Elisp, this is handled by the language
>> > server. Eglot arranges for language-server-provided function help to
>> > be displayed by ElDoc.
>>
>> What about an equivalent of the *Help* buffer?
>
> Well, what about it? You move the point to an identifier. Its
> signature and a few lines of documentation are shown in the echo area.
> You invoke (eldoc-doc-buffer) and see the whole documentation.
>
> It may be a bit inconvenient that the content of that buffer changes
> as you move point to a different identifier. But that can be worked
> around with (clone-buffer).

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,
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.  References to other
predicates become links to their corresponding *Help* buffers, just like
we have for Elisp.  It even works for user-defined predicates.


Cheers,
Eshel

Re: Documentation by function beyond elisp

[João Távora]

On Fri, Mar 10, 2023 at 2:51 PM Eshel Yaron <me@eshelyaron.com> wrote:
>
> Yuri Khan <yuri.v.khan@gmail.com> writes:
>
> > On Fri, 10 Mar 2023 at 16:12, Ihor Radchenko <yantar92@posteo.net> wrote:
> >>
> >> Yuri Khan <yuri.v.khan@gmail.com> writes:
> >>
> >> > For languages other than Elisp, this is handled by the language
> >> > server. Eglot arranges for language-server-provided function help to
> >> > be displayed by ElDoc.
> >>
> >> What about an equivalent of the *Help* buffer?
> >
> > Well, what about it? You move the point to an identifier. Its
> > signature and a few lines of documentation are shown in the echo area.
> > You invoke (eldoc-doc-buffer) and see the whole documentation.
> >
> > It may be a bit inconvenient that the content of that buffer changes
> > as you move point to a different identifier. But that can be worked
> > around with (clone-buffer).
>
> IMO ElDoc and Help and two pretty different features, each with its own
> use and purpose.

They are different in implementation, but there is definitely overlap,
and not in small amount.  I'm not saying this is ideal, but that's
what it is. Both features show documentation for language elements.

One difference is that it is just much easier to hook up ElDoc to
multiple asynchronous and synchronous documentation providing features,
such as Eglot's LSP interface, but also SLY, SLIME, CIDER as examples.

Also, using help-mode, the major mode must do all the window
management and documentation rendering.  It's not immediately
clear if it can be used to exert generic control over how
documentation is displayed, like eldoc.el can.  It's also not
immediately clear how to use it with asynchronous documentation
sources.

Eldoc.el lives in lisp/emacs-lisp, but it was effectively already
being used for other languages and modes long before I reworked
some of its interfaces.  The manual is very underdeveloped, but
IMHO a much more promising feature.  I myself have never used *Help*
for anything but Emacs lisp, where I do appreciate it immensely.

> Eglot integrates with ElDoc but not with Help AFAIU,
> but language-specific packages can (and should!) integrate
> with both of these facilities.

I'm not saying the contrary, but I'd say that for a new mode
for language-x it's easier to setup Eldoc with an external
documentation-producing program, an inferior process (like
SLY/CIDER) leave it to LSP via Eglot.  Fully fleshing out a
*Help* renderer like you did in sweeprolog.el seems a lot
more work.

João

Re: Documentation by function beyond elisp

[Augusto Stoffel]

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.

> 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'.  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).

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

Re: Documentation by function beyond elisp

[Eshel Yaron]

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.