bug#31754: 25.1; etags output lacks info for making xref more useful

bug#31754: 25.1; etags output lacks info for making xref more useful

[Gauthier Östervall]

Given the following code:

---8<---
int my_identifier(int a) {
    return 2 * a;
}

int my_identifier(int a, int b) {
    return a + b;
}
---8<---

and a TAGS file generated with etags (no options).

Running xref-find-definitions (M-.) opens a suggestion buffer with this content:

---8<---
/home/gauthier/tmp/xref.c
1: int my_identifier(
5: int my_identifier(
---8<---

This could be more helpful, the suggestions are not distinguishable. I
suggest including at least the whole source row.

The example source is only a minimal example, obviously not a real problem in
C. This disturbs me when I have multiple identifier definitions.

---

In GNU Emacs 25.1.1 (x86_64-pc-linux-gnu, GTK+ Version 3.22.11)
 of 2017-09-15, modified by Debian built on trouble
Windowing system distributor 'The X.Org Foundation', version 11.0.11902000
System Description: Debian GNU/Linux 9.4 (stretch)

Configured using:
 'configure --build x86_64-linux-gnu --prefix=/usr
 --sharedstatedir=/var/lib --libexecdir=/usr/lib
 --localstatedir=/var/lib --infodir=/usr/share/info
 --mandir=/usr/share/man --with-pop=yes
 --enable-locallisppath=/etc/emacs25:/etc/emacs:/usr/local/share/emacs/25.1/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/25.1/site-lisp:/usr/share/emacs/site-lisp
 --with-sound=alsa --build x86_64-linux-gnu --prefix=/usr
 --sharedstatedir=/var/lib --libexecdir=/usr/lib
 --localstatedir=/var/lib --infodir=/usr/share/info
 --mandir=/usr/share/man --with-pop=yes
 --enable-locallisppath=/etc/emacs25:/etc/emacs:/usr/local/share/emacs/25.1/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/25.1/site-lisp:/usr/share/emacs/site-lisp
 --with-sound=alsa --with-x=yes --with-x-toolkit=gtk3
 --with-toolkit-scroll-bars 'CFLAGS=-g -O2
 -fdebug-prefix-map=/build/emacs25-wN2qS3/emacs25-25.1+1=.
-fstack-protector-strong
 -Wformat -Werror=format-security -Wall' 'CPPFLAGS=-Wdate-time
 -D_FORTIFY_SOURCE=2' LDFLAGS=-Wl,-z,relro'

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

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

Major mode: robot mode

Minor modes in effect:
  magit-auto-revert-mode: t
  auto-revert-mode: t
  dumb-jump-mode: t
  flx-ido-mode: t
  global-git-commit-mode: t
  async-bytecomp-package-mode: t
  shell-dirtrack-mode: t
  diff-auto-refine-mode: t
  ido-everywhere: t
  global-cwarn-mode: t
  dtrt-indent-mode: t
  show-paren-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-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: (only)

Recent messages:
Type C-c C-c to finish, or C-c C-k to cancel
(No changes need to be saved)
Saving file /home/gauthier/.emacs.d/whsettings...
Wrote /home/gauthier/.emacs.d/whsettings
File TAGS is large (11.7M), really open? (y or n) y
Note: indent-tabs-mode adjusted to nil
Mark set [2 times]
Saving file /home/gauthier/.emacs.d/whsettings...
Wrote /home/gauthier/.emacs.d/whsettings
Mark saved where search started

Load-path shadows:
/home/gauthier/.emacs.d/elpa/git-commit-20171007.346/git-commit hides
~/.emacs.d/includes/git-commit
/usr/share/emacs/25.1/site-lisp/debian-startup hides
/usr/share/emacs/site-lisp/debian-startup
/usr/share/emacs25/site-lisp/cmake-data/cmake-mode hides
/usr/share/emacs/site-lisp/cmake-mode
~/.emacs.d/includes/ruby-mode hides
/usr/share/emacs/25.1/lisp/progmodes/ruby-mode

Features:
(shadow sort mail-extr emacsbug sendmail conf-mode flyspell ispell
magit-obsolete magit-blame magit-stash magit-bisect magit-remote
magit-commit epa magit-sequence magit-notes magit-worktree magit-branch
magit-files magit-refs magit-status subr-x magit esh-var esh-io esh-cmd
esh-opt esh-ext esh-proc esh-arg esh-groups eshell esh-module esh-mode
esh-util dired-x magit-repos magit-apply magit-wip magit-log magit-diff
smerge-mode magit-core magit-autorevert autorevert filenotify
magit-process magit-margin magit-mode magit-git magit-section
magit-popup disp-table blank-mode rect misearch multi-isearch projectile
grep ibuf-ext vc-bzr vc-hg haskell-doc inf-haskell haskell-decl-scan
imenu haskell haskell-completions haskell-load haskell-commands
highlight-uses-mode haskell-modules haskell-sandbox
haskell-navigate-imports haskell-repl haskell-collapse hideshow
haskell-debug haskell-interactive-mode haskell-presentation-mode
haskell-compile haskell-hoogle haskell-process haskell-session url-util
url-parse auth-source url-vars json map haskell-mode haskell-cabal
haskell-utils haskell-font-lock haskell-indentation haskell-string
haskell-sort-imports haskell-lexeme rx haskell-align-imports
haskell-compat haskell-complete-module haskell-ghc-support noutline
outline flymake dabbrev haskell-customize dumb-jump popup f etags xref
project eieio eieio-core fill-column-indicator flx-ido flx
google-c-style visual defaultcontent buffer-move windmove git-commit
with-editor async-bytecomp async shell pcomplete server magit-utils
vc-git diff-mode crm log-edit easy-mmode message format-spec rfc822 mml
mml-sec password-cache epg gnus-util mm-decode mm-bodies mm-encode
mail-parse rfc2231 rfc2047 rfc2045 ietf-drums mm-util help-fns
mail-prsvr mailabbrev mail-utils gmm-utils mailheader pcvs-util add-log
highlight-symbol thingatpt copy ws-trim pymacs python-mode info-look
darkroom-mode frame-local-vars w32-fullscreen gas-mode revbufs ido
ibuffer ag vc-svn cl-seq derived compile comint ansi-color ring
find-dired s dash dired column-marker bisque-darker-theme
smart-mode-line cl-macs cl cwarn cc-mode cc-fonts cc-guess cc-menus
cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs hl-line dtrt-indent
cus-start cus-load advice paren finder-inf edmacro kmacro
highlight-symbol-autoloads rainbow-mode-autoloads info package
epg-config seq byte-opt gv bytecomp byte-compile cl-extra help-mode
easymenu cconv cl-loaddefs pcase cl-lib 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
move-toolbar gtk x-toolkit x multi-tty make-network-process emacs)

Memory information:
((conses 16 885150 128230)
 (symbols 48 39371 0)
 (miscs 40 951 1965)
 (strings 32 83523 14685)
 (string-bytes 1 2857273)
 (vectors 16 61900)
 (vector-slots 8 2683541 97025)
 (floats 8 8004 1127)
 (intervals 56 6166 738)
 (buffers 976 33))

bug#31754: 25.1; etags output lacks info for making xref more useful

[Eli Zaretskii]

severity 31754 wishlist
thanks

> From: Gauthier Östervall <gauthier@ostervall.se>
> Date: Fri, 8 Jun 2018 11:21:54 +0200
> 
> Given the following code:
> 
> ---8<---
> int my_identifier(int a) {
>     return 2 * a;
> }
> 
> int my_identifier(int a, int b) {
>     return a + b;
> }
> ---8<---
> 
> and a TAGS file generated with etags (no options).
> 
> Running xref-find-definitions (M-.) opens a suggestion buffer with this content:
> 
> ---8<---
> /home/gauthier/tmp/xref.c
> 1: int my_identifier(
> 5: int my_identifier(
> ---8<---
> 
> This could be more helpful, the suggestions are not distinguishable. I
> suggest including at least the whole source row.

I originally thought that etags should be extended to include the
while line in TAGS, at least as an option, but the more I think about
this, the less I'm convinced thats the right approach.  For starters,
no one said that line will show enough to tell the difference.  For
example, imagine this code:

  int my_identifier(int a,
		    int b) {
      return 2 * a + b;
  }

  int my_identifier(int a,
		    int b, double fac) {
      return fac*a + b;
  }

So now I think that perhaps we should leave etags alone, and instead
add a feature to xref whereby the lines in the XREF buffer will show
in a tooltip the full signature of the function.

Any takers?

bug#31754: 25.1; etags output lacks info for making xref more useful

[Gauthier Östervall]

On Mon, Jun 11, 2018 at 7:46 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> severity 31754 wishlist
> thanks
>
>> From: Gauthier Östervall <gauthier@ostervall.se>
>> Date: Fri, 8 Jun 2018 11:21:54 +0200
>> This could be more helpful, the suggestions are not distinguishable. I
>> suggest including at least the whole source row.
>
> I originally thought that etags should be extended to include the
> while line in TAGS, at least as an option, but the more I think about
> this, the less I'm convinced thats the right approach.  For starters,
> no one said that line will show enough to tell the difference.  For
> example, imagine this code:
>
>   int my_identifier(int a,
>                     int b) {
>       return 2 * a + b;
>   }
>
>   int my_identifier(int a,
>                     int b, double fac) {
>       return fac*a + b;
>   }
>

Agreed, showing the whole row is not enough.

> So now I think that perhaps we should leave etags alone, and instead
> add a feature to xref whereby the lines in the XREF buffer will show
> in a tooltip the full signature of the function.

I am not a fan of tooltips, to be honest. I guess I'm not alone here.
I like to visually grep all the suggestions then go to the right one
fast, instead of needing to put my cursor on every row before I can
see their tooltip.

In order to show the full signature, XREF would need to parse the
source files. etags is already parsing files anyway, I can't see why
not let it save whole signatures to TAGS?

bug#31754: 25.1; etags output lacks info for making xref more useful

[Eli Zaretskii]

> From: Gauthier Östervall <gauthier@ostervall.se>
> Date: Tue, 12 Jun 2018 16:49:44 +0200
> Cc: 31754@debbugs.gnu.org
> 
> > So now I think that perhaps we should leave etags alone, and instead
> > add a feature to xref whereby the lines in the XREF buffer will show
> > in a tooltip the full signature of the function.
> 
> I am not a fan of tooltips, to be honest.

It's standard UI for these cases.  But we could, of course, have an
option whereby the XREF buffer itself would display enough of the
function's beginning to show the same info.

> In order to show the full signature, XREF would need to parse the
> source files.

Well, "parse" is really an exaggeration here.  More like "display the
first sexp", I'd say.  Every programming language mode already knows
how to do such limited "parsing".

> etags is already parsing files anyway, I can't see why not let it
> save whole signatures to TAGS?

Because it will bloat TAGS by a large factor.  Think about large
projects with hundreds of source files.  Even in Emacs, which is not
such a large package by modern standards, the combined TAGS table
weighs in at about 4MB.  The larger TAGS, the slower searches and
completion based on it.

It isn't TAGS' role, anyway.  TAGS is there to provide "links" to the
places in sources where functions are defined, it only shows the text
at that place for 2 purposes: (1) so that links won't break when the
source file changes in small ways, and the function moves to a
different line/byte offset; and (2) to show the identifier (the
function's name) itself, so as to allow Emacs to find in TAGS the
identifier the user requests.  Anything else is something Xref should
do when it finds the place where TAGS points, IMO.  Besides, this
feature will I think be valuable with Xref back-ends other than etags.