* Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*
[not found] ` <20220331113841.3BBFAC0581F@vcs2.savannah.gnu.org>
@ 2022-03-31 13:05 ` Robert Pluim
2022-03-31 18:12 ` Stefan Monnier
0 siblings, 1 reply; 8+ messages in thread
From: Robert Pluim @ 2022-03-31 13:05 UTC (permalink / raw)
To: emacs-devel; +Cc: Lars Ingebrigtsen
>>>>> On Thu, 31 Mar 2022 07:38:39 -0400 (EDT), Lars Ingebrigtsen <larsi@gnus.org> said:
Lars> @@ -1098,7 +1098,7 @@ MET-NAME is as returned by `cl--generic-load-hist-format'."
Lars> (dolist (method (cl--generic-method-table generic))
Lars> (let* ((info (cl--generic-method-info method)))
Lars> ;; FIXME: Add hyperlinks for the types as well.
Lars> - (insert (format "%s%S" (nth 0 info) (nth 1 info)))
Lars> + (insert (format "%s%S" (nth 0 info) (cons function (nth 1 info))))
Is it worth applying `upcase' to the (nth 1 info) so the result looks
more like C-h f output?
Robert
--
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*
2022-03-31 13:05 ` master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help* Robert Pluim
@ 2022-03-31 18:12 ` Stefan Monnier
2022-04-02 13:22 ` Lars Ingebrigtsen
0 siblings, 1 reply; 8+ messages in thread
From: Stefan Monnier @ 2022-03-31 18:12 UTC (permalink / raw)
To: Robert Pluim; +Cc: emacs-devel, Lars Ingebrigtsen
> Lars> @@ -1098,7 +1098,7 @@ MET-NAME is as returned by `cl--generic-load-hist-format'."
> Lars> (dolist (method (cl--generic-method-table generic))
> Lars> (let* ((info (cl--generic-method-info method)))
> Lars> ;; FIXME: Add hyperlinks for the types as well.
> Lars> - (insert (format "%s%S" (nth 0 info) (nth 1 info)))
> Lars> + (insert (format "%s%S" (nth 0 info) (cons function (nth 1 info))))
>
> Is it worth applying `upcase' to the (nth 1 info) so the result looks
> more like C-h f output?
If so, we should be careful to only apply it to the argnames but not to
the specializers since these are case sensitive.
The above patch also leads to odd results for methods with qualifiers.
E.g. `C-h o cl-generic-generalizers RET` shows things like:
:extra "cl-struct" (cl-generic-generalizers type) in ‘cl-generic.el’.
Undocumented
which I find rather confusing. I understand the motivation for the
change, but I'm not sure it's an improvement.
(and I don't know what would be a good way to combine the qualifiers
with the function name).
Stefan
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*
2022-03-31 18:12 ` Stefan Monnier
@ 2022-04-02 13:22 ` Lars Ingebrigtsen
2022-04-02 14:26 ` Stefan Monnier
0 siblings, 1 reply; 8+ messages in thread
From: Lars Ingebrigtsen @ 2022-04-02 13:22 UTC (permalink / raw)
To: Stefan Monnier; +Cc: Robert Pluim, emacs-devel
Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> Is it worth applying `upcase' to the (nth 1 info) so the result looks
>> more like C-h f output?
>
> If so, we should be careful to only apply it to the argnames but not to
> the specializers since these are case sensitive.
Yup. But, yes, I think it would make sense to upcase/italicize the
argnames, because that would clarify what we're talking about here
(which isn't at all obvious). Patches welcome.
> The above patch also leads to odd results for methods with qualifiers.
> E.g. `C-h o cl-generic-generalizers RET` shows things like:
>
> :extra "cl-struct" (cl-generic-generalizers type) in ‘cl-generic.el’.
>
> Undocumented
>
> which I find rather confusing.
I've now made those things display as before, but I think it's not quite
clear what that part is trying to express, so some clarification here
would be nice.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*
2022-04-02 13:22 ` Lars Ingebrigtsen
@ 2022-04-02 14:26 ` Stefan Monnier
2022-04-02 14:41 ` Lars Ingebrigtsen
0 siblings, 1 reply; 8+ messages in thread
From: Stefan Monnier @ 2022-04-02 14:26 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: Robert Pluim, emacs-devel
>> If so, we should be careful to only apply it to the argnames but not to
>> the specializers since these are case sensitive.
> Yup. But, yes, I think it would make sense to upcase/italicize the
> argnames, because that would clarify what we're talking about here
> (which isn't at all obvious). Patches welcome.
Agreed.
>> The above patch also leads to odd results for methods with qualifiers.
>> E.g. `C-h o cl-generic-generalizers RET` shows things like:
>>
>> :extra "cl-struct" (cl-generic-generalizers type) in ‘cl-generic.el’.
>>
>> Undocumented
>>
>> which I find rather confusing.
>
> I've now made those things display as before, but I think it's not quite
> clear what that part is trying to express, so some clarification here
> would be nice.
The new behavior is weird/confusing. I get (with manual
capitalization, while we wait for an actual patch):
[...]
(cl-generic-generalizers (SPECIALIZER (head derived-mode))) in ‘cl-generic.el’.
Support for (derived-mode MODE) specializers.
Used internally for the (major-mode MODE) context specializers.
:extra "typeof" (TYPE) in ‘cl-generic.el’.
[...]
The presence/absence of `cl-generic-generalizers` looks rather
accidental/unexplained (IOW looks like a bug to me :-)
For reference, these correspond to:
(cl-defmethod cl-generic-generalizers ((specializer (head derived-mode))))
and
(cl-defmethod cl-generic-generalizers :extra "typeof" (type)
in the source code.
Stefan
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*
2022-04-02 14:26 ` Stefan Monnier
@ 2022-04-02 14:41 ` Lars Ingebrigtsen
2022-04-02 19:30 ` Stefan Monnier
0 siblings, 1 reply; 8+ messages in thread
From: Lars Ingebrigtsen @ 2022-04-02 14:41 UTC (permalink / raw)
To: Stefan Monnier; +Cc: Robert Pluim, emacs-devel
Stefan Monnier <monnier@iro.umontreal.ca> writes:
> Used internally for the (major-mode MODE) context specializers.
>
> :extra "typeof" (TYPE) in ‘cl-generic.el’.
>
> [...]
>
> The presence/absence of `cl-generic-generalizers` looks rather
> accidental/unexplained (IOW looks like a bug to me :-)
I don't think it's more confusing than before, though. :-/
> For reference, these correspond to:
>
> (cl-defmethod cl-generic-generalizers ((specializer (head derived-mode))))
>
> and
>
> (cl-defmethod cl-generic-generalizers :extra "typeof" (type)
>
> in the source code.
I think the :extra thing should also be formatted as they're supposed to
be used in code. (And I really have no idea what that's supposed to
be.)
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*
2022-04-02 14:41 ` Lars Ingebrigtsen
@ 2022-04-02 19:30 ` Stefan Monnier
2022-04-03 11:57 ` Lars Ingebrigtsen
0 siblings, 1 reply; 8+ messages in thread
From: Stefan Monnier @ 2022-04-02 19:30 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: Robert Pluim, emacs-devel
Lars Ingebrigtsen [2022-04-02 16:41:36] wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>> Used internally for the (major-mode MODE) context specializers.
>>
>> :extra "typeof" (TYPE) in ‘cl-generic.el’.
>>
>> [...]
>>
>> The presence/absence of `cl-generic-generalizers` looks rather
>> accidental/unexplained (IOW looks like a bug to me :-)
>
> I don't think it's more confusing than before, though. :-/
Before your recent changes it was:
[...]
((SPECIALIZER (head derived-mode))) in ‘cl-generic.el’.
Support for (derived-mode MODE) specializers.
Used internally for the (major-mode MODE) context specializers.
:extra "typeof" (TYPE) in ‘cl-generic.el’.
[...]
So the text matched the part after `(cl-defmethod cl-generic-generalizers`
in the source code:
(cl-defmethod cl-generic-generalizers ((specializer (head derived-mode))))
and
(cl-defmethod cl-generic-generalizers :extra "typeof" (type)
Maybe a way to solve the problem is to use something like:
[...]
(cl-generic-generalizers (SPECIALIZER (head derived-mode))) in ‘cl-generic.el’.
Support for (derived-mode MODE) specializers.
Used internally for the (major-mode MODE) context specializers.
(cl-generic-generalizers TYPE) in ‘cl-generic.el’.
:extra "typeof"
[...]
Of course the `cl-generic-generalizers` is always redundant and risks
pushing the line length past the window width, which was some of the
reasons why I originally used just:
[...]
((SPECIALIZER (head derived-mode))) in ‘cl-generic.el’.
Support for (derived-mode MODE) specializers.
Used internally for the (major-mode MODE) context specializers.
:extra "typeof" (TYPE) in ‘cl-generic.el’.
[...]
-- Stefan
^ permalink raw reply [flat|nested] 8+ messages in thread* Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*
2022-04-02 19:30 ` Stefan Monnier
@ 2022-04-03 11:57 ` Lars Ingebrigtsen
2022-04-03 16:18 ` Stefan Monnier
0 siblings, 1 reply; 8+ messages in thread
From: Lars Ingebrigtsen @ 2022-04-03 11:57 UTC (permalink / raw)
To: Stefan Monnier; +Cc: Robert Pluim, emacs-devel
Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> I don't think it's more confusing than before, though. :-/
>
> Before your recent changes it was:
>
> [...]
>
> ((SPECIALIZER (head derived-mode))) in ‘cl-generic.el’.
>
> Support for (derived-mode MODE) specializers.
> Used internally for the (major-mode MODE) context specializers.
>
> :extra "typeof" (TYPE) in ‘cl-generic.el’.
And I found that very confusing -- I didn't really know what it was
trying to express before this bug report.
> Maybe a way to solve the problem is to use something like:
>
> [...]
>
> (cl-generic-generalizers (SPECIALIZER (head derived-mode))) in
> ‘cl-generic.el’.
>
> Support for (derived-mode MODE) specializers.
> Used internally for the (major-mode MODE) context specializers.
>
> (cl-generic-generalizers TYPE) in ‘cl-generic.el’.
> :extra "typeof"
I still don't understand what the :extra "typeof" is trying to tell me.
:-)
> Of course the `cl-generic-generalizers` is always redundant and risks
> pushing the line length past the window width, which was some of the
> reasons why I originally used just:
We could format this better, yes.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*
2022-04-03 11:57 ` Lars Ingebrigtsen
@ 2022-04-03 16:18 ` Stefan Monnier
0 siblings, 0 replies; 8+ messages in thread
From: Stefan Monnier @ 2022-04-03 16:18 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: Robert Pluim, emacs-devel
>> (cl-generic-generalizers TYPE) in ‘cl-generic.el’.
>> :extra "typeof"
>
> I still don't understand what the :extra "typeof" is trying to tell me.
> :-)
Not sure what we can do about it, tho. It's not like qualifiers (which
are what those things are) are self evident if you don't know
about them, indeed.
This is compounded by the fact that this particular qualifier is
specific to ELisp (the more usual qualifiers are `:after`, `:before`,
and `:around`).
Stefan
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2022-04-03 16:18 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <164872671963.30191.4037902323881017518@vcs2.savannah.gnu.org>
[not found] ` <20220331113841.3BBFAC0581F@vcs2.savannah.gnu.org>
2022-03-31 13:05 ` master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help* Robert Pluim
2022-03-31 18:12 ` Stefan Monnier
2022-04-02 13:22 ` Lars Ingebrigtsen
2022-04-02 14:26 ` Stefan Monnier
2022-04-02 14:41 ` Lars Ingebrigtsen
2022-04-02 19:30 ` Stefan Monnier
2022-04-03 11:57 ` Lars Ingebrigtsen
2022-04-03 16:18 ` Stefan Monnier
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).