all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#57974: 2022-08-30; Enhancing help facility for function doc string
       [not found] <1509.1663752344@localhost>
@ 2022-09-21 10:15 ` Ikumi Keita
  2022-09-21 11:56 ` Lars Ingebrigtsen
  1 sibling, 0 replies; 10+ messages in thread
From: Ikumi Keita @ 2022-09-21 10:15 UTC (permalink / raw)
  To: 57974

Oops, sorry. I sent to wrong address. I reassigned this from "auctex" to
"emacs".

>>>>> Ikumi Keita <ikumi@ikumi.que.jp> writes:
> This is a wishlist for record rather than a bug report. See
> <URL:https://lists.gnu.org/r/auctex-devel/2022-09/msg00046.html> for the
> background.

> When a Elisp function A has :override advice B, help facility (C-h f)
> displays doc string A, not B. It only indicates
> This function has :override advice: THE-NAME-OF-B
> modestly.

> This is inconvenient, especially when A is a (major or minor) mode
> function and the user typed C-h m in that mode buffer.

> It would be worth considering to enhance the help facility to display
> doc string of B instead when A is overrided by advice.

> Regards,
> Ikumi Keita
> #StandWithUkraine #StopWarInUkraine





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

* bug#57974: 2022-08-30; Enhancing help facility for function doc string
       [not found] <1509.1663752344@localhost>
  2022-09-21 10:15 ` bug#57974: 2022-08-30; Enhancing help facility for function doc string Ikumi Keita
@ 2022-09-21 11:56 ` Lars Ingebrigtsen
  2022-09-21 14:21   ` Ikumi Keita
  1 sibling, 1 reply; 10+ messages in thread
From: Lars Ingebrigtsen @ 2022-09-21 11:56 UTC (permalink / raw)
  To: Ikumi Keita; +Cc: 57974

Ikumi Keita <ikumi@ikumi.que.jp> writes:

> This is a wishlist for record rather than a bug report. See
> <URL:https://lists.gnu.org/r/auctex-devel/2022-09/msg00046.html> for the
> background.
>
> When a Elisp function A has :override advice B, help facility (C-h f)
> displays doc string A, not B. It only indicates
> This function has :override advice: THE-NAME-OF-B
> modestly.
>
> This is inconvenient, especially when A is a (major or minor) mode
> function and the user typed C-h m in that mode buffer.
>
> It would be worth considering to enhance the help facility to display
> doc string of B instead when A is overrided by advice.

I'm not quite sure I follow your meaning here.

Do you have a complete recipe, starting from "emacs -Q", that displays
the problem?





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

* bug#57974: 2022-08-30; Enhancing help facility for function doc string
  2022-09-21 11:56 ` Lars Ingebrigtsen
@ 2022-09-21 14:21   ` Ikumi Keita
  2022-09-22 11:13     ` Lars Ingebrigtsen
  0 siblings, 1 reply; 10+ messages in thread
From: Ikumi Keita @ 2022-09-21 14:21 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: 57974

Hi Lars,

>>>>> Lars Ingebrigtsen <larsi@gnus.org> writes:
> I'm not quite sure I follow your meaning here.

> Do you have a complete recipe, starting from "emacs -Q", that displays
> the problem?

1. Save the following file as /tmp/foo.el
----------------------------------------------------------------------
(defun func-A ()
  "doc string of A"
  nil)

(defun func-B ()
  "doc string of B"
  t)

(advice-add 'func-A :override #'func-B)
----------------------------------------------------------------------
2. emacs -Q -l /tmp/foo.el
3. Type C-h f func-A RET
4. Then *Help* buffer pops up and shows
----------------------------------------------------------------------
func-A is a Lisp function in ‘/tmp/foo.el’.

(func-A)

doc string of A

This function has :override advice: ‘func-B’.
----------------------------------------------------------------------
The function A behaves as if it were the function B by the nature of
:override advice, so the doc string of A is almost useless. The actual
behavior is described by the doc string of B.

Unfortunately, when A is a mode function and has a long doc string,
users can easily look over the line
This function has :override advice: ‘func-B’.
far downward in the *Help* buffer when they see the output of C-h m.
That results in that they miss the "true" mode description provided by
the doc string of B.

Stephan suggested that such situation can be improved as
,----
| Maybe the help facility should be more careful in how it builds the
| docstring when a function has an `:override` advice, indeed.
`----
, in https://lists.gnu.org/r/auctex-devel/2022-09/msg00046.html

Regards,
Ikumi Keita
#StandWithUkraine #StopWarInUkraine





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

* bug#57974: 2022-08-30; Enhancing help facility for function doc string
  2022-09-21 14:21   ` Ikumi Keita
@ 2022-09-22 11:13     ` Lars Ingebrigtsen
  2022-09-22 14:26       ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
  0 siblings, 1 reply; 10+ messages in thread
From: Lars Ingebrigtsen @ 2022-09-22 11:13 UTC (permalink / raw)
  To: Ikumi Keita; +Cc: Stefan Monnier, 57974

Ikumi Keita <ikumi@ikumi.que.jp> writes:

> The function A behaves as if it were the function B by the nature of
> :override advice, so the doc string of A is almost useless. The actual
> behavior is described by the doc string of B.
>
> Unfortunately, when A is a mode function and has a long doc string,
> users can easily look over the line
> This function has :override advice: ‘func-B’.
> far downward in the *Help* buffer when they see the output of C-h m.
> That results in that they miss the "true" mode description provided by
> the doc string of B.
>
> Stephan suggested that such situation can be improved as
> ,----
> | Maybe the help facility should be more careful in how it builds the
> | docstring when a function has an `:override` advice, indeed.
> `----
> , in https://lists.gnu.org/r/auctex-devel/2022-09/msg00046.html

Right, makes sense.  But there can be more than one advice -- would
moving just the :overrides to the front of the doc string solve the
problem?






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

* bug#57974: 2022-08-30; Enhancing help facility for function doc string
  2022-09-22 11:13     ` Lars Ingebrigtsen
@ 2022-09-22 14:26       ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2022-09-22 15:22         ` Ikumi Keita
  0 siblings, 1 reply; 10+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-09-22 14:26 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: Ikumi Keita, 57974

> Right, makes sense.  But there can be more than one advice -- would
> moving just the :overrides to the front of the doc string solve the
> problem?

It used to be there, so maybe that's a good solution, yes.


        Stefan






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

* bug#57974: 2022-08-30; Enhancing help facility for function doc string
  2022-09-22 14:26       ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2022-09-22 15:22         ` Ikumi Keita
  2022-09-22 16:47           ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
  0 siblings, 1 reply; 10+ messages in thread
From: Ikumi Keita @ 2022-09-22 15:22 UTC (permalink / raw)
  To: Lars Ingebrigtsen, Stefan Monnier; +Cc: 57974

>>>>> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> Right, makes sense.  But there can be more than one advice -- would
>> moving just the :overrides to the front of the doc string solve the
>> problem?

> It used to be there, so maybe that's a good solution, yes.

More radical approach would also be an option, i.e., to display doc
string of B instead of A; but I don't strongly insist.

Bye,
Ikumi Keita
#StandWithUkraine #StopWarInUkraine





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

* bug#57974: 2022-08-30; Enhancing help facility for function doc string
  2022-09-22 15:22         ` Ikumi Keita
@ 2022-09-22 16:47           ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
  2022-09-23 15:10             ` Lars Ingebrigtsen
  0 siblings, 1 reply; 10+ messages in thread
From: Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-09-22 16:47 UTC (permalink / raw)
  To: Ikumi Keita; +Cc: Lars Ingebrigtsen, 57974

Ikumi Keita [2022-09-23 00:22:06] wrote:
>>>>>> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>>> Right, makes sense.  But there can be more than one advice -- would
>>> moving just the :overrides to the front of the doc string solve the
>>> problem?
>> It used to be there, so maybe that's a good solution, yes.
> More radical approach would also be an option, i.e., to display doc
> string of B instead of A; but I don't strongly insist.

I don't have a strong opinion either.  I think the issue has more to do
about how to implement it (the info about advice is provided via the
same mechanism used for all kinds of other auxiliary info and is not
designed to distinguish those things that are more or less important,
it has a very limited flexibility right now).


        Stefan






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

* bug#57974: 2022-08-30; Enhancing help facility for function doc string
  2022-09-22 16:47           ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2022-09-23 15:10             ` Lars Ingebrigtsen
  2022-09-24  6:04               ` Ikumi Keita
  0 siblings, 1 reply; 10+ messages in thread
From: Lars Ingebrigtsen @ 2022-09-23 15:10 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Ikumi Keita, 57974

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I don't have a strong opinion either.  I think the issue has more to do
> about how to implement it (the info about advice is provided via the
> same mechanism used for all kinds of other auxiliary info and is not
> designed to distinguish those things that are more or less important,
> it has a very limited flexibility right now).

Today, I think the display is something along the lines of:

---
func-A is a Lisp function in /tmp/foo.el.

(func-A)

doc string of A

This function has :after advice: func-D.
This function has :before advice: func-C.
This function has :override advice: func-B.
---

Moving the :override line to the start would be easy enough, but should
perhaps also be rephrased to something like:

---
This function has :override advice: func-B, so func-A isn't run at all,
and the documentation below is possibly irrelevant.  See the
documentation to func-B instead.
---






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

* bug#57974: 2022-08-30; Enhancing help facility for function doc string
  2022-09-23 15:10             ` Lars Ingebrigtsen
@ 2022-09-24  6:04               ` Ikumi Keita
  2022-09-24 12:06                 ` Lars Ingebrigtsen
  0 siblings, 1 reply; 10+ messages in thread
From: Ikumi Keita @ 2022-09-24  6:04 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: Stefan Monnier, 57974

Hi Lars,

>>>>> Lars Ingebrigtsen <larsi@gnus.org> writes:
> Moving the :override line to the start would be easy enough, but should
> perhaps also be rephrased to something like:

> ---
> This function has :override advice: func-B, so func-A isn't run at all,
> and the documentation below is possibly irrelevant.  See the
> documentation to func-B instead.
> ---

Thanks, I think the proposed stuff is organized well enough.

Regards,
Ikumi Keita
#StandWithUkraine #StopWarInUkraine





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

* bug#57974: 2022-08-30; Enhancing help facility for function doc string
  2022-09-24  6:04               ` Ikumi Keita
@ 2022-09-24 12:06                 ` Lars Ingebrigtsen
  0 siblings, 0 replies; 10+ messages in thread
From: Lars Ingebrigtsen @ 2022-09-24 12:06 UTC (permalink / raw)
  To: Ikumi Keita; +Cc: Stefan Monnier, 57974

Ikumi Keita <ikumi@ikumi.que.jp> writes:

> Thanks, I think the proposed stuff is organized well enough.

I've now done this in Emacs 29.





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

end of thread, other threads:[~2022-09-24 12:06 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <1509.1663752344@localhost>
2022-09-21 10:15 ` bug#57974: 2022-08-30; Enhancing help facility for function doc string Ikumi Keita
2022-09-21 11:56 ` Lars Ingebrigtsen
2022-09-21 14:21   ` Ikumi Keita
2022-09-22 11:13     ` Lars Ingebrigtsen
2022-09-22 14:26       ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-09-22 15:22         ` Ikumi Keita
2022-09-22 16:47           ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-09-23 15:10             ` Lars Ingebrigtsen
2022-09-24  6:04               ` Ikumi Keita
2022-09-24 12:06                 ` Lars Ingebrigtsen

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.