all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Documentation by function beyond elisp 
@ 2023-03-09 11:33 goncholden
  2023-03-09 12:07 ` Po Lu
                   ` (2 more replies)
  0 siblings, 3 replies; 20+ messages in thread
From: goncholden @ 2023-03-09 11:33 UTC (permalink / raw)
  To: emacs-devel@gnu.org

[-- 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 --]

^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 11:33 Documentation by function beyond elisp goncholden
@ 2023-03-09 12:07 ` Po Lu
  2023-03-09 12:17   ` goncholden
  2023-03-09 12:24 ` Eli Zaretskii
  2023-03-09 15:50 ` Yuri Khan
  2 siblings, 1 reply; 20+ messages in thread
From: Po Lu @ 2023-03-09 12:07 UTC (permalink / raw)
  To: goncholden; +Cc: emacs-devel@gnu.org

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.



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 12:07 ` Po Lu
@ 2023-03-09 12:17   ` goncholden
  2023-03-09 13:33     ` Po Lu
  0 siblings, 1 reply; 20+ messages in thread
From: goncholden @ 2023-03-09 12:17 UTC (permalink / raw)
  To: Po Lu; +Cc: emacs-devel@gnu.org

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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 11:33 Documentation by function beyond elisp goncholden
  2023-03-09 12:07 ` Po Lu
@ 2023-03-09 12:24 ` Eli Zaretskii
  2023-03-09 13:01   ` goncholden
  2023-03-09 15:50 ` Yuri Khan
  2 siblings, 1 reply; 20+ messages in thread
From: Eli Zaretskii @ 2023-03-09 12:24 UTC (permalink / raw)
  To: goncholden; +Cc: emacs-devel

> 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"?



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 12:24 ` Eli Zaretskii
@ 2023-03-09 13:01   ` goncholden
  2023-03-09 15:29     ` Eli Zaretskii
  2023-03-09 15:48     ` Eli Zaretskii
  0 siblings, 2 replies; 20+ messages in thread
From: goncholden @ 2023-03-09 13:01 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel


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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 12:17   ` goncholden
@ 2023-03-09 13:33     ` Po Lu
  2023-03-09 13:58       ` goncholden
  0 siblings, 1 reply; 20+ messages in thread
From: Po Lu @ 2023-03-09 13:33 UTC (permalink / raw)
  To: goncholden; +Cc: emacs-devel@gnu.org

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.




^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 13:33     ` Po Lu
@ 2023-03-09 13:58       ` goncholden
  0 siblings, 0 replies; 20+ messages in thread
From: goncholden @ 2023-03-09 13:58 UTC (permalink / raw)
  To: Po Lu; +Cc: emacs-devel@gnu.org


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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 13:01   ` goncholden
@ 2023-03-09 15:29     ` Eli Zaretskii
  2023-03-09 15:36       ` goncholden
  2023-03-09 15:48     ` Eli Zaretskii
  1 sibling, 1 reply; 20+ messages in thread
From: Eli Zaretskii @ 2023-03-09 15:29 UTC (permalink / raw)
  To: goncholden; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 15:29     ` Eli Zaretskii
@ 2023-03-09 15:36       ` goncholden
  0 siblings, 0 replies; 20+ messages in thread
From: goncholden @ 2023-03-09 15:36 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel


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




^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 13:01   ` goncholden
  2023-03-09 15:29     ` Eli Zaretskii
@ 2023-03-09 15:48     ` Eli Zaretskii
  2023-03-09 17:04       ` goncholden
  1 sibling, 1 reply; 20+ messages in thread
From: Eli Zaretskii @ 2023-03-09 15:48 UTC (permalink / raw)
  To: goncholden; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp
  2023-03-09 11:33 Documentation by function beyond elisp goncholden
  2023-03-09 12:07 ` Po Lu
  2023-03-09 12:24 ` Eli Zaretskii
@ 2023-03-09 15:50 ` Yuri Khan
  2023-03-10  9:14   ` Ihor Radchenko
  2 siblings, 1 reply; 20+ messages in thread
From: Yuri Khan @ 2023-03-09 15:50 UTC (permalink / raw)
  To: goncholden; +Cc: emacs-devel@gnu.org

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.



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 15:48     ` Eli Zaretskii
@ 2023-03-09 17:04       ` goncholden
  2023-03-09 17:33         ` Eli Zaretskii
  0 siblings, 1 reply; 20+ messages in thread
From: goncholden @ 2023-03-09 17:04 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel


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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp 
  2023-03-09 17:04       ` goncholden
@ 2023-03-09 17:33         ` Eli Zaretskii
  0 siblings, 0 replies; 20+ messages in thread
From: Eli Zaretskii @ 2023-03-09 17:33 UTC (permalink / raw)
  To: goncholden; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp
  2023-03-09 15:50 ` Yuri Khan
@ 2023-03-10  9:14   ` Ihor Radchenko
  2023-03-10 10:23     ` Yuri Khan
  0 siblings, 1 reply; 20+ messages in thread
From: Ihor Radchenko @ 2023-03-10  9:14 UTC (permalink / raw)
  To: Yuri Khan; +Cc: goncholden, emacs-devel@gnu.org

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>



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp
  2023-03-10  9:14   ` Ihor Radchenko
@ 2023-03-10 10:23     ` Yuri Khan
  2023-03-10 14:43       ` João Távora
  2023-03-10 14:50       ` Eshel Yaron
  0 siblings, 2 replies; 20+ messages in thread
From: Yuri Khan @ 2023-03-10 10:23 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: goncholden, emacs-devel@gnu.org

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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp
  2023-03-10 10:23     ` Yuri Khan
@ 2023-03-10 14:43       ` João Távora
  2023-03-10 14:50       ` Eshel Yaron
  1 sibling, 0 replies; 20+ messages in thread
From: João Távora @ 2023-03-10 14:43 UTC (permalink / raw)
  To: Yuri Khan; +Cc: Ihor Radchenko, goncholden, emacs-devel@gnu.org

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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp
  2023-03-10 10:23     ` Yuri Khan
  2023-03-10 14:43       ` João Távora
@ 2023-03-10 14:50       ` Eshel Yaron
  2023-03-10 15:33         ` João Távora
  2023-03-11 10:46         ` Augusto Stoffel
  1 sibling, 2 replies; 20+ messages in thread
From: Eshel Yaron @ 2023-03-10 14:50 UTC (permalink / raw)
  To: Yuri Khan; +Cc: Ihor Radchenko, goncholden, emacs-devel@gnu.org

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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp
  2023-03-10 14:50       ` Eshel Yaron
@ 2023-03-10 15:33         ` João Távora
  2023-03-11 10:46         ` Augusto Stoffel
  1 sibling, 0 replies; 20+ messages in thread
From: João Távora @ 2023-03-10 15:33 UTC (permalink / raw)
  To: Eshel Yaron; +Cc: Yuri Khan, Ihor Radchenko, goncholden, emacs-devel@gnu.org

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



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp
  2023-03-10 14:50       ` Eshel Yaron
  2023-03-10 15:33         ` João Távora
@ 2023-03-11 10:46         ` Augusto Stoffel
  2023-03-11 19:04           ` Eshel Yaron
  1 sibling, 1 reply; 20+ messages in thread
From: Augusto Stoffel @ 2023-03-11 10:46 UTC (permalink / raw)
  To: Eshel Yaron; +Cc: Yuri Khan, Ihor Radchenko, goncholden, emacs-devel@gnu.org

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?



^ permalink raw reply	[flat|nested] 20+ messages in thread

* Re: Documentation by function beyond elisp
  2023-03-11 10:46         ` Augusto Stoffel
@ 2023-03-11 19:04           ` Eshel Yaron
  0 siblings, 0 replies; 20+ messages in thread
From: Eshel Yaron @ 2023-03-11 19:04 UTC (permalink / raw)
  To: Augusto Stoffel
  Cc: Yuri Khan, Ihor Radchenko, goncholden, emacs-devel@gnu.org

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.



^ permalink raw reply	[flat|nested] 20+ messages in thread

end of thread, other threads:[~2023-03-11 19:04 UTC | newest]

Thread overview: 20+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-03-09 11:33 Documentation by function beyond elisp goncholden
2023-03-09 12:07 ` Po Lu
2023-03-09 12:17   ` goncholden
2023-03-09 13:33     ` Po Lu
2023-03-09 13:58       ` goncholden
2023-03-09 12:24 ` Eli Zaretskii
2023-03-09 13:01   ` goncholden
2023-03-09 15:29     ` Eli Zaretskii
2023-03-09 15:36       ` goncholden
2023-03-09 15:48     ` Eli Zaretskii
2023-03-09 17:04       ` goncholden
2023-03-09 17:33         ` Eli Zaretskii
2023-03-09 15:50 ` Yuri Khan
2023-03-10  9:14   ` Ihor Radchenko
2023-03-10 10:23     ` Yuri Khan
2023-03-10 14:43       ` João Távora
2023-03-10 14:50       ` Eshel Yaron
2023-03-10 15:33         ` João Távora
2023-03-11 10:46         ` Augusto Stoffel
2023-03-11 19:04           ` Eshel Yaron

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.