GNU bug report logs - #69935
[PATCH] (help-fns-function-description-header): Print functions' type

Previous Next

To reply to this bug, email your comments to 69935 AT debbugs.gnu.org.

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

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] (help-fns-function-description-header): Print functions' type
Date: Thu, 21 Mar 2024 21:22:39 -0400

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

Tags: patch

The patch below changes the first line of `C-h f` from something like:

    car is a built-in function in ‘C source code’.

to

    car is a primitive-function in ‘C source code’.

i.e. print the actual type rather than an English description.
The type is buttonized so users can click on it to see a description of
the type (and its super/subtypes).

Beside exposing those types (and their related information), another
advantage is that it simplifies the code since we don't need to
enumerate all the different kinds of functions we may have (well, we
still do for those "function-like objects" which don't have a dedicated
type such as macros, keymaps, aliases, keyboard macros, yadda yadda, but
a single case covers all of special forms, primitive functions,
byte-code functions, module functions, and native-compiled functions).

Any comment/objection?


        Stefan

 In GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
 3.24.38, cairo version 1.16.0) of 2024-02-23 built on pastel
Repository revision: 831e094a09f70a15e4b4b83c5158dbeb8d9daede
Repository branch: work
Windowing system distributor 'The X.Org Foundation', version 11.0.12101007
System Description: Debian GNU/Linux 12 (bookworm)

Configured using:
 'configure -C --enable-checking --enable-check-lisp-object-type --with-modules --with-cairo --with-tiff=ifavailable
 'CFLAGS=-Wall -g3 -Og -Wno-pointer-sign' --without-native-compilation
 PKG_CONFIG_PATH=/home/monnier/lib/pkgconfig'

[0001-help-fns-function-description-header-Print-functions.patch (text/patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 69935 <at> debbugs.gnu.org
Subject: Re: bug#69935: [PATCH] (help-fns-function-description-header): Print
 functions' type
Date: Fri, 22 Mar 2024 09:25:58 +0200

> Date: Thu, 21 Mar 2024 21:22:39 -0400
> From:  Stefan Monnier via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> The patch below changes the first line of `C-h f` from something like:
> 
>     car is a built-in function in ‘C source code’.
> 
> to
> 
>     car is a primitive-function in ‘C source code’.
> 
> i.e. print the actual type rather than an English description.
> The type is buttonized so users can click on it to see a description of
> the type (and its super/subtypes).
> 
> Beside exposing those types (and their related information), another
> advantage is that it simplifies the code since we don't need to
> enumerate all the different kinds of functions we may have (well, we
> still do for those "function-like objects" which don't have a dedicated
> type such as macros, keymaps, aliases, keyboard macros, yadda yadda, but
> a single case covers all of special forms, primitive functions,
> byte-code functions, module functions, and native-compiled functions).
> 
> Any comment/objection?

No objections, but IMO this should be in NEWS, and the button and
its purpose should be described in the user manual (where we document
"C-h f").

Thanks.

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

From: Andrea Corallo <acorallo <at> gnu.org>
To: 69935 <at> debbugs.gnu.org
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#69935: [PATCH] (help-fns-function-description-header):
 Print functions' type
Date: Fri, 22 Mar 2024 11:39:57 -0400

Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of
text editors" <bug-gnu-emacs <at> gnu.org> writes:

> Tags: patch
>
> The patch below changes the first line of `C-h f` from something like:
>
>     car is a built-in function in ‘C source code’.
>
> to
>
>     car is a primitive-function in ‘C source code’.
>
> i.e. print the actual type rather than an English description.
> The type is buttonized so users can click on it to see a description of
> the type (and its super/subtypes).
>
> Beside exposing those types (and their related information), another
> advantage is that it simplifies the code since we don't need to
> enumerate all the different kinds of functions we may have (well, we
> still do for those "function-like objects" which don't have a dedicated
> type such as macros, keymaps, aliases, keyboard macros, yadda yadda, but
> a single case covers all of special forms, primitive functions,
> byte-code functions, module functions, and native-compiled functions).
>
> Any comment/objection?

Hi Stefan,

I like it thanks!  I think we might want to highlight the
inferred/declared argument/ret types as well WDYT?

I might implement something along this line once your patch is.

Thanks

  Andrea

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 69935 <at> debbugs.gnu.org
Subject: Re: bug#69935: [PATCH] (help-fns-function-description-header):
 Print functions' type
Date: Fri, 22 Mar 2024 17:14:40 -0400

> No objections, but IMO this should be in NEWS,

Good point, just added, thanks.

> and the button and its purpose should be described in the user manual
> (where we document "C-h f").

Hmm.. not sure where/how to add it there.  The current text doesn't
discuss/mention the other buttons (like the button to jump to the
source) and auxiliary information, so I'm not sure what you
were expecting.  My proposal would be something like the text below.
Is that the kind of thing you were thinking about?

[ Side note: I already pushed my proposed patch (without doc changes,
  obviously) accidentally when I pushed another change.
  Sorry 'bout that.  ]


        Stefan


diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 05457a3f34f..a6136ad6554 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -310,6 +310,12 @@ Name Help
 @kbd{C-h f} command if you don't really want to view the
 documentation.
 
+  The function's documentation displayed by @code{describe-function}
+includes more than just the documentation string and the signature of
+the function.  It also shows auxiliary information such as its type,
+the file where it was defined, whether it has been declared obsolete,
+etc...
+
 @vindex help-enable-symbol-autoload
   If you request help for an autoloaded function whose @code{autoload}
 form (@pxref{Autoload,,, elisp, The Emacs Lisp Reference Manual})

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 69935 <at> debbugs.gnu.org
Subject: Re: bug#69935: [PATCH] (help-fns-function-description-header):
 Print functions' type
Date: Sat, 23 Mar 2024 08:44:09 +0200

> From: Stefan Monnier <monnier <at> iro.umontreal.ca>
> Cc: 69935 <at> debbugs.gnu.org
> Date: Fri, 22 Mar 2024 17:14:40 -0400
> 
> > and the button and its purpose should be described in the user manual
> > (where we document "C-h f").
> 
> Hmm.. not sure where/how to add it there.  The current text doesn't
> discuss/mention the other buttons (like the button to jump to the
> source) and auxiliary information, so I'm not sure what you
> were expecting.  My proposal would be something like the text below.
> Is that the kind of thing you were thinking about?

Yes, except that I would suggest to mention that some of the auxiliary
information is reachable by clicking or typing RET on hyperlink-style
emphasized parts of the text displayed in the *Help* buffer.

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 69935 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#69935: [PATCH] (help-fns-function-description-header): Print
 functions' type
Date: Fri, 28 Feb 2025 19:07:12 -0800

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

>> From: Stefan Monnier <monnier <at> iro.umontreal.ca>
>> Cc: 69935 <at> debbugs.gnu.org
>> Date: Fri, 22 Mar 2024 17:14:40 -0400
>>
>> > and the button and its purpose should be described in the user manual
>> > (where we document "C-h f").
>>
>> Hmm.. not sure where/how to add it there.  The current text doesn't
>> discuss/mention the other buttons (like the button to jump to the
>> source) and auxiliary information, so I'm not sure what you
>> were expecting.  My proposal would be something like the text below.
>> Is that the kind of thing you were thinking about?
>
> Yes, except that I would suggest to mention that some of the auxiliary
> information is reachable by clicking or typing RET on hyperlink-style
> emphasized parts of the text displayed in the *Help* buffer.

Stefan, did you install the documentation changes here?

I see that the patch itself is installed already.  Thanks.

Previous Next

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