GNU bug report logs - #61877
[PATCH] Extract Lisp function examples from shortdoc information

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 61877 in the body.
You can then email your comments to 61877 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Daniel Martín <mardani29 <at> yahoo.es>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Extract Lisp function examples from shortdoc information
Date: Tue, 28 Feb 2023 23:36:09 +0100

[Message part 1 (text/plain, inline)]

Shortdoc contains a lot of useful examples about how to use common ELisp
functions.  This patch explores a new Emacs feature where those examples
are identified and extracted so they can be displayed, perhaps, in
*Help* buffers (via an additional help-fns-describe-function-functions
hook).

After you install the attached patch, take a look at the *Help* buffer
produced by C-h f assq RET, or C-h f match-string RET, etc.

What do you think of having this new Lisp feature in Emacs 30?  I can
send later another patch with tests, relevant NEWS entries and
documentation changes.

Thanks.

[0001-Extract-Lisp-function-examples-from-shortdoc-informa.patch (text/x-patch, attachment)]

Message #8 received at 61877 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Martín <mardani29 <at> yahoo.es>
To: 61877 <at> debbugs.gnu.org
Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc
 information
Date: Thu, 02 Mar 2023 22:38:42 +0100

[Message part 1 (text/plain, inline)]

Daniel Martín <mardani29 <at> yahoo.es> writes:

> Shortdoc contains a lot of useful examples about how to use common ELisp
> functions.  This patch explores a new Emacs feature where those examples
> are identified and extracted so they can be displayed, perhaps, in
> *Help* buffers (via an additional help-fns-describe-function-functions
> hook).
>
> After you install the attached patch, take a look at the *Help* buffer
> produced by C-h f assq RET, or C-h f match-string RET, etc.
>
> What do you think of having this new Lisp feature in Emacs 30?  I can
> send later another patch with tests, relevant NEWS entries and
> documentation changes.
>
> Thanks.

I attach a second version of the patch.  I've confined the
implementation to shortdoc.el, added a test, and documented the new
functions.

The NEWS entry explains how users could show this information in their
*Help* buffers, if they want.

Thanks.

[0001-Add-functions-to-query-Emacs-Lisp-examples-registere.patch (text/x-patch, attachment)]

Message #11 received at 61877 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Martín <mardani29 <at> yahoo.es>
Cc: 61877 <at> debbugs.gnu.org
Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc
 information
Date: Sat, 11 Mar 2023 10:37:54 +0200

> Date: Thu, 02 Mar 2023 22:38:42 +0100
> From:  Daniel Martín via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> Daniel Martín <mardani29 <at> yahoo.es> writes:
> 
> > Shortdoc contains a lot of useful examples about how to use common ELisp
> > functions.  This patch explores a new Emacs feature where those examples
> > are identified and extracted so they can be displayed, perhaps, in
> > *Help* buffers (via an additional help-fns-describe-function-functions
> > hook).
> >
> > After you install the attached patch, take a look at the *Help* buffer
> > produced by C-h f assq RET, or C-h f match-string RET, etc.
> >
> > What do you think of having this new Lisp feature in Emacs 30?  I can
> > send later another patch with tests, relevant NEWS entries and
> > documentation changes.
> >
> > Thanks.
> 
> I attach a second version of the patch.  I've confined the
> implementation to shortdoc.el, added a test, and documented the new
> functions.

Thanks.  This no longer applies to the current master, so please
resubmit, and I will install.

> The NEWS entry explains how users could show this information in their
> *Help* buffers, if they want.

Maybe this part should be also in the user manual?

Message #14 received at 61877 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Martín <mardani29 <at> yahoo.es>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61877 <at> debbugs.gnu.org
Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc
 information
Date: Sat, 11 Mar 2023 15:27:54 +0100

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>
> Thanks.  This no longer applies to the current master, so please
> resubmit, and I will install.
>

Thanks, I've rebased the patch.

>> The NEWS entry explains how users could show this information in their
>> *Help* buffers, if they want.
>
> Maybe this part should be also in the user manual?

I've added some information to the user manual.  I see we don't document
help-fns-describe-function-functions in the user manual at all, should
we do it?  Customizing what is displayed in describe-function buffers
may be something that users want to do.  But perhaps we need to make the
hook part of the Customize interface first, I don't know.

[0001-Add-functions-to-query-Emacs-Lisp-examples-registere.patch (text/x-patch, attachment)]

Message #17 received at 61877 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Martín <mardani29 <at> yahoo.es>
Cc: 61877 <at> debbugs.gnu.org
Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc
 information
Date: Sun, 12 Mar 2023 10:30:14 +0200

> From: Daniel Martín <mardani29 <at> yahoo.es>
> Cc: 61877 <at> debbugs.gnu.org
> Date: Sat, 11 Mar 2023 15:27:54 +0100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >
> > Thanks.  This no longer applies to the current master, so please
> > resubmit, and I will install.
> >
> 
> Thanks, I've rebased the patch.
> 
> >> The NEWS entry explains how users could show this information in their
> >> *Help* buffers, if they want.
> >
> > Maybe this part should be also in the user manual?
> 
> I've added some information to the user manual.  I see we don't document
> help-fns-describe-function-functions in the user manual at all, should
> we do it?  Customizing what is displayed in describe-function buffers
> may be something that users want to do.  But perhaps we need to make the
> hook part of the Customize interface first, I don't know.

I added an index entry for help-fns-describe-function-functions in the
ELisp manual; I think this is enough for now.

Now installed on master.

Btw, something seems amiss: "C-h f" for string-fill, which has 2
examples in shortdoc, still says "Example:", not "Examples:", as I'd
expect.  Can you take a look?

Message #20 received at 61877 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Martín <mardani29 <at> yahoo.es>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61877 <at> debbugs.gnu.org
Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc
 information
Date: Sun, 12 Mar 2023 13:55:49 +0100

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

> Btw, something seems amiss: "C-h f" for string-fill, which has 2
> examples in shortdoc, still says "Example:", not "Examples:", as I'd
> expect.  Can you take a look?

That is because some functions have more than one example per group (for
example, string-lessp is documented in the "comparison" and "string"
groups), but the "s" is added when a function is documented in _more
than one group_.

I think a more accurate logic to add the "s" is to count the number of
"arrow characters" that separate the form from the example.

Could you give a try to the attached patch, and install it for me if all
works correctly?  Thanks.

[0001-Fix-pluralization-in-shortdoc-help-fns-examples-func.patch (text/x-patch, attachment)]

Message #23 received at 61877 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Martín <mardani29 <at> yahoo.es>
Cc: 61877 <at> debbugs.gnu.org
Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc
 information
Date: Sun, 12 Mar 2023 15:25:26 +0200

> From: Daniel Martín <mardani29 <at> yahoo.es>
> Cc: 61877 <at> debbugs.gnu.org
> Date: Sun, 12 Mar 2023 13:55:49 +0100
> 
> > Btw, something seems amiss: "C-h f" for string-fill, which has 2
> > examples in shortdoc, still says "Example:", not "Examples:", as I'd
> > expect.  Can you take a look?
> 
> That is because some functions have more than one example per group (for
> example, string-lessp is documented in the "comparison" and "string"
> groups), but the "s" is added when a function is documented in _more
> than one group_.
> 
> I think a more accurate logic to add the "s" is to count the number of
> "arrow characters" that separate the form from the example.
> 
> Could you give a try to the attached patch, and install it for me if all
> works correctly?  Thanks.

It works here; I installed it.

Thanks.

Message #28 received at 61877-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61877-done <at> debbugs.gnu.org,
 Daniel Martín <mardani29 <at> yahoo.es>
Subject: Re: bug#61877: [PATCH] Extract Lisp function examples from shortdoc
 information
Date: Tue, 5 Sep 2023 17:03:39 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Could you give a try to the attached patch, and install it for me if all
>> works correctly?  Thanks.
>
> It works here; I installed it.

I'm therefore closing this bug report.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.