bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 5264 bytes --]


In a buffer with python-mode, after run Emacs function
'info-lookup-symbol', Emacs ask which mode would provide him infos about
Python symbols. I can choose between c-mode, awk-mode, etc, but there's
no python-mode provided. :(

It would be nice if python-mode provide infos about Python symbols.
Informations about Python symbols can be found with the executable
'pydoc' provided with the Python interpreter.



Emacs informations:
In GNU Emacs 25.3.1 (x86_64-redhat-linux-gnu, GTK+ Version 3.22.26)
 of 2018-01-12 built on buildhw-08.phx2.fedoraproject.org
Windowing system distributor 'Fedora Project', version 11.0.11906000
Configured using:
 'configure --build=x86_64-redhat-linux-gnu
 --host=x86_64-redhat-linux-gnu --program-prefix=
 --disable-dependency-tracking --prefix=/usr --exec-prefix=/usr
 --bindir=/usr/bin --sbindir=/usr/sbin --sysconfdir=/etc
 --datadir=/usr/share --includedir=/usr/include --libdir=/usr/lib64
 --libexecdir=/usr/libexec --localstatedir=/var
 --sharedstatedir=/var/lib --mandir=/usr/share/man
 --infodir=/usr/share/info --with-dbus --with-gif --with-jpeg --with-png
 --with-rsvg --with-tiff --with-xft --with-xpm --with-x-toolkit=gtk3
 --with-gpm=no --with-xwidgets --with-modules
 build_alias=x86_64-redhat-linux-gnu host_alias=x86_64-redhat-linux-gnu
 'CFLAGS=-DMAIL_USE_LOCKF -O2 -g -pipe -Wall -Werror=format-security
 -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector-strong
 --param=ssp-buffer-size=4 -grecord-gcc-switches
 -specs=/usr/lib/rpm/redhat/redhat-hardened-cc1
 -specs=/usr/lib/rpm/redhat/redhat-annobin-cc1 -m64 -mtune=generic'
 LDFLAGS=-Wl,-z,relro
 PKG_CONFIG_PATH=:/usr/lib64/pkgconfig:/usr/share/pkgconfig'

Configured features:
XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK SOUND DBUS GCONF GSETTINGS NOTIFY
ACL LIBSELINUX GNUTLS LIBXML2 FREETYPE M17N_FLT LIBOTF XFT ZLIB
TOOLKIT_SCROLL_BARS GTK3 X11 MODULES XWIDGETS

Important settings:
  value of $LANG: fr_CH.utf8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: Python

Minor modes in effect:
  diff-auto-refine-mode: t
  shell-dirtrack-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent messages:
Loading /usr/share/emacs/site-lisp/site-start.d/rpmdev-init.el (source)...done
Loading /usr/share/emacs/site-lisp/site-start.d/systemtap-init.el (source)...done
For information about GNU Emacs and the GNU system, type C-h C-a.
completing-read-default: Command attempted to use minibuffer while in minibuffer
Type C-x 1 to delete the help window, C-M-v to scroll help.
mwheel-scroll: Beginning of buffer [5 times]
Type C-x 1 to delete the help window, C-M-v to scroll help.
Making completion list...
Quit
Type C-x 1 to delete the help window.

Load-path shadows:
/usr/share/emacs/site-lisp/gnus-bonus/spam-stat hides /usr/share/emacs/25.3/lisp/gnus/spam-stat
/usr/share/emacs/site-lisp/gnus-bonus/nnir hides /usr/share/emacs/25.3/lisp/gnus/nnir
/usr/share/emacs/site-lisp/gnus-bonus/nnnil hides /usr/share/emacs/25.3/lisp/gnus/nnnil

Features:
(shadow sort mail-extr emacsbug message idna dired rfc822 mml mml-sec
epg epg-config mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums
mail-utils eieio-opt speedbar sb-image ezimage dframe find-func
info-look info thai-util thai-word vc-git diff-mode python tramp-sh
tramp tramp-compat auth-source cl-seq eieio eieio-core gnus-util mm-util
help-fns mail-prsvr password-cache tramp-loaddefs trampver ucs-normalize
shell pcomplete format-spec advice json map seq byte-opt bytecomp
byte-compile cl-extra help-mode cconv comint ring ansi-color
preview-latex emacs-goodies-loaddefs easy-mmode color-theme easymenu
wid-edit cl clang-format cl-macs gv xml cl-loaddefs pcase cl-lib
auto-loads tex-site time-date mule-util tooltip eldoc electric uniquify
ediff-hook vc-hooks lisp-float-type mwheel x-win term/common-win x-dnd
tool-bar dnd fontset image regexp-opt fringe tabulated-list newcomment
elisp-mode lisp-mode prog-mode register page menu-bar rfn-eshadow timer
select scroll-bar mouse jit-lock font-lock syntax facemenu font-core
frame cl-generic cham georgian utf-8-lang misc-lang vietnamese tibetan
thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek romanian
slovak czech european ethiopic indian cyrillic chinese charscript
case-table epa-hook jka-cmpr-hook help simple abbrev minibuffer
cl-preloaded nadvice loaddefs button faces cus-face macroexp files
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote dbusbind inotify
dynamic-setting system-font-setting font-render-setting xwidget-internal
move-toolbar gtk x-toolkit x multi-tty make-network-process emacs)

Memory information:
((conses 16 324765 10369)
 (symbols 48 36664 0)
 (miscs 40 753 304)
 (strings 32 45612 10684)
 (string-bytes 1 1305850)
 (vectors 16 43460)
 (vector-slots 8 1003375 37580)
 (floats 8 255 172)
 (intervals 56 457 0)
 (buffers 976 22))

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[npostavs]

tags 31405 + moreinfo
quit

seb@k-7.ch (Sébastien Gendre) writes:

> In a buffer with python-mode, after run Emacs function
> 'info-lookup-symbol', Emacs ask which mode would provide him infos about
> Python symbols. I can choose between c-mode, awk-mode, etc, but there's
> no python-mode provided. :(
>
> It would be nice if python-mode provide infos about Python symbols.
> Informations about Python symbols can be found with the executable
> 'pydoc' provided with the Python interpreter.

Does 'pydoc' provide output formatted as .info though?  Not sure if this
feature request makes sense.

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Stefan Kangas]

npostavs@gmail.com writes:

> tags 31405 + moreinfo
> quit
>
> seb@k-7.ch (Sébastien Gendre) writes:
>
>> In a buffer with python-mode, after run Emacs function
>> 'info-lookup-symbol', Emacs ask which mode would provide him infos about
>> Python symbols. I can choose between c-mode, awk-mode, etc, but there's
>> no python-mode provided. :(
>>
>> It would be nice if python-mode provide infos about Python symbols.
>> Informations about Python symbols can be found with the executable
>> 'pydoc' provided with the Python interpreter.
>
> Does 'pydoc' provide output formatted as .info though?  Not sure if this
> feature request makes sense.

Sphinx is used to generate Python docs AFAIK, and it supports info
format output.  There is also the MELPA package python-info which is
"a simple Emacs package to provide an info manual for Python":

https://github.com/wilfred/python-info

Perhaps we should support that use case in vanilla Emacs?  One can
always hope that more GNU/Linux distributions takes the hint and
starts generating and shipping the info files for Python.  (And that
interested users files bugs with their respective GNU/Linux
distribution, Homebrew for OSX, etc. if they don't already do that.)

Thanks,
Stefan Kangas

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Sphinx is used to generate Python docs AFAIK, and it supports info
> format output.  There is also the MELPA package python-info which is
> "a simple Emacs package to provide an info manual for Python":
>
> https://github.com/wilfred/python-info
>
> Perhaps we should support that use case in vanilla Emacs?  One can
> always hope that more GNU/Linux distributions takes the hint and
> starts generating and shipping the info files for Python.  (And that
> interested users files bugs with their respective GNU/Linux
> distribution, Homebrew for OSX, etc. if they don't already do that.)

The Melpa package doesn't seem to exist any more?  So I'm guessing there
isn't much demand for an Info manual for Python, so adding support for
it in info-look would just be frustrating the users, I think.

On the other hand, you have a point that if Emacs did provide hooks into
Info, then perhaps it'd entice people to start distributing .info
files...

Hm...

Oh!  I was looking in melpa-stable -- python-info is indeed in melpa.

OK, I've now added support for python-mode in info-lookup-symbol, and
seems to work in my one test, which was looking up "date", which took me
to:

 -- Class: datetime.date (year, month, day)

     All arguments are required.  Arguments may be ints or longs, in the
     following ranges:

Which seems correct.  People who actually use Python should probably
change 

(info-lookup-maybe-add-help
 :mode 'python-mode
 :doc-spec '(("(python)Index")))

to something that filters/matches more accurately, perhaps.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Basil L. Contovounesios via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> Sphinx is used to generate Python docs AFAIK, and it supports info
>> format output.  There is also the MELPA package python-info which is
>> "a simple Emacs package to provide an info manual for Python":
>>
>> https://github.com/wilfred/python-info
>>
>> Perhaps we should support that use case in vanilla Emacs?  One can
>> always hope that more GNU/Linux distributions takes the hint and
>> starts generating and shipping the info files for Python.  (And that
>> interested users files bugs with their respective GNU/Linux
>> distribution, Homebrew for OSX, etc. if they don't already do that.)
>
> The Melpa package doesn't seem to exist any more?  So I'm guessing there
> isn't much demand for an Info manual for Python, so adding support for
> it in info-look would just be frustrating the users, I think.
>
> On the other hand, you have a point that if Emacs did provide hooks into
> Info, then perhaps it'd entice people to start distributing .info
> files...

FWIW, Debian packages the latest Python Info manual as python3-doc.

> Hm...
>
> Oh!  I was looking in melpa-stable -- python-info is indeed in melpa.

Yes, but at first glance it seems to be specific to Python 2 and hasn't
been updated in 6 years.

> OK, I've now added support for python-mode in info-lookup-symbol, and
> seems to work in my one test, which was looking up "date", which took me
> to:
>
>  -- Class: datetime.date (year, month, day)
>
>      All arguments are required.  Arguments may be ints or longs, in the
>      following ranges:
>
> Which seems correct.  People who actually use Python should probably
> change 
>
> (info-lookup-maybe-add-help
>  :mode 'python-mode
>  :doc-spec '(("(python)Index")))
>
> to something that filters/matches more accurately, perhaps.

In my case I have to override it as

  (with-eval-after-load 'info-look
    (info-lookup-add-help
     :mode 'python-mode
     :doc-spec '(("(python3.9)Index"))))

to match the name and version of the manual installed by Debian.

Thanks,

-- 
Basil

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Lars Ingebrigtsen]

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

> In my case I have to override it as
>
>   (with-eval-after-load 'info-look
>     (info-lookup-add-help
>      :mode 'python-mode
>      :doc-spec '(("(python3.9)Index"))))
>
> to match the name and version of the manual installed by Debian.

I've now adjusted the code to look for the 3.9 manual, but I haven't
actually tested.  And perhaps it should ... look even more for newer
versions, but I don't know quite how -- just loop over a bunch of
version numbers?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Basil L. Contovounesios via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> "Basil L. Contovounesios" <contovob@tcd.ie> writes:
>
>> In my case I have to override it as
>>
>>   (with-eval-after-load 'info-look
>>     (info-lookup-add-help
>>      :mode 'python-mode
>>      :doc-spec '(("(python3.9)Index"))))
>>
>> to match the name and version of the manual installed by Debian.
>
> I've now adjusted the code to look for the 3.9 manual, but I haven't
> actually tested.

Thanks, I just tweaked it there and it works OOTB for me.

> And perhaps it should ... look even more for newer
> versions,

And older versions - an update to Debian Stable is imminent, but for now
it still ships Python 3.7 (I run Debian Testing).

> but I don't know quite how -- just loop over a bunch of
> version numbers?

Ideally the info/info-look machinery would match a regexp, no?  Perhaps
that's already supported, but I'm unfamiliar with those libraries.

Thanks,

-- 
Basil

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Eli Zaretskii]

> Cc: seb@k-7.ch, Stefan Kangas <stefan@marxist.se>,
>  Noam Postavsky <npostavs@gmail.com>, 31405@debbugs.gnu.org
> Date: Thu, 12 Aug 2021 16:13:34 +0100
> From:  "Basil L. Contovounesios" via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> > (info-lookup-maybe-add-help
> >  :mode 'python-mode
> >  :doc-spec '(("(python)Index")))
> >
> > to something that filters/matches more accurately, perhaps.
> 
> In my case I have to override it as
> 
>   (with-eval-after-load 'info-look
>     (info-lookup-add-help
>      :mode 'python-mode
>      :doc-spec '(("(python3.9)Index"))))
> 
> to match the name and version of the manual installed by Debian.

IMNSHO, it's a bug in Debian that they include the version in the file
name and don't provide any symlink or other way of getting the Python
Info manual.  That's not how the Info system was designed to work.

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Thu, 12 Aug 2021 17:21:58 +0200
> Cc: 31405@debbugs.gnu.org, Stefan Kangas <stefan@marxist.se>,
>  Noam Postavsky <npostavs@gmail.com>, seb@k-7.ch
> 
> "Basil L. Contovounesios" <contovob@tcd.ie> writes:
> 
> > In my case I have to override it as
> >
> >   (with-eval-after-load 'info-look
> >     (info-lookup-add-help
> >      :mode 'python-mode
> >      :doc-spec '(("(python3.9)Index"))))
> >
> > to match the name and version of the manual installed by Debian.
> 
> I've now adjusted the code to look for the 3.9 manual

If Debian is including the version in the file name, and we want to
support that, I think we should have a defcustom for users to control
which version they want Emacs to look for.  Or maybe we should allow a
list of file names there, and then we could mention all the known
names for reasonably recent versions of Python.

Again, the Info system is not designed to support that.  For example,
hyperlinks from other manuals won't work reliably, and you'd have
trouble with the system-wide DIR file, if you ever dare updating it
outside of Debian's control.

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> IMNSHO, it's a bug in Debian that they include the version in the file
> name and don't provide any symlink or other way of getting the Python
> Info manual.  That's not how the Info system was designed to work.

Yeah, the file is called

python3.9-doc: /usr/share/info/python3.9.info.gz

and there's no symlink.  Python is slightly ... special, I guess, since
there's the constant in-fighting about python2/3, but it's still pretty
odd.

Eli Zaretskii <eliz@gnu.org> writes:

> If Debian is including the version in the file name, and we want to
> support that, I think we should have a defcustom for users to control
> which version they want Emacs to look for.  Or maybe we should allow a
> list of file names there, and then we could mention all the known
> names for reasonably recent versions of Python.
>
> Again, the Info system is not designed to support that.  For example,
> hyperlinks from other manuals won't work reliably, and you'd have
> trouble with the system-wide DIR file, if you ever dare updating it
> outside of Debian's control.

Yeah, it's far from ideal.  But I think we can try to be helpful in
info-look, at least -- I'll add some further code to try to do a trivial
search in the python3.* name space.  I don't think adding a variable
here should be necessary.  If it turns out that our guesses are wrong,
then the user can do

  (with-eval-after-load 'info-look
    (info-lookup-add-help
     :mode 'python-mode
     :doc-spec '(("(python-some-weird-name)Index"))))

as Basil suggested.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Augusto Stoffel]

FWIW, the Info version of the Python manual doesn't look very good.  The
(only) reason being that Info doesn't let you write a plain hyperlink in
the middle of a sentence; rather it assumes that all hyperlinks are part
of the phrase “See [link target].”.

Since the Python manual wasn't written specifically for Texinfo, it has
lots of hyperlinks, and so will say things like "this function takes a
see string. as argument and return a see boolean."

I brought this up in [1], but unfortunately the Texinfo people seem to
like this limitation a lot.

By the way, this issue is what led me to write the devdocs [2] package.

[1] https://lists.gnu.org/archive/html/bug-texinfo/2021-05/msg00022.html
[2] https://elpa.gnu.org/packages/devdocs.html

bug#31405: 25.3; Python.el doesn't provide infos to info-lookup-symbol

[Eli Zaretskii]

> From: Augusto Stoffel <arstoffel@gmail.com>
> Date: Sat, 28 Aug 2021 11:56:10 +0200
> Cc: contovob@tcd.ie, larsi@gnus.org, stefan@marxist.se, npostavs@gmail.com,
>  seb@k-7.ch
> 
> FWIW, the Info version of the Python manual doesn't look very good.  The
> (only) reason being that Info doesn't let you write a plain hyperlink in
> the middle of a sentence; rather it assumes that all hyperlinks are part
> of the phrase “See [link target].”.
> 
> Since the Python manual wasn't written specifically for Texinfo, it has
> lots of hyperlinks, and so will say things like "this function takes a
> see string. as argument and return a see boolean."

That's because they use tools that mainly target HTML docs, and don't
much care about the other output formats.  These inline references
look badly in print.  GCC is migrating to the same tools, and its
manuals will have the same problems (because people who drive this
migration don't seem to care too much about Info, either).

> I brought this up in [1], but unfortunately the Texinfo people seem to
> like this limitation a lot.

The way to overcome this difficulty is to use Texinfo macros, so that
these inline references look in HTML as HTML users expect, but at the
same time don't uglify Info or PS/PDF output.  I believe this was
mentioned on the Texinfo list more than once.