mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-03-20 22:03:14 -07:00
Code Issues Projects Releases Wiki Activity
emacs/etc
History
João Távora a7a53f0d79 Better handle asynchronous Eldoc sources 
This is a backward compatible redesign of significant parts of the
eldoc.el library.

Previously, Eldoc clients (major/minor modes setting its documentation
gathering variables) needed to directly call eldoc-message, an
internal function, to display the docstring to the user.  When more
asynchronous sources are involved, this is hard to do or even breaks
down.

Now, an Eldoc backend may return any non-nil, non-string value and
call a callback afterwards.  This restores power to Eldoc over how
(and crucially also when) to display the docstrings to the user.

Among other things, this fixes so called "doc blinking", or the very
short-lived display of a lower priority Eldoc message.  This would
happen if a particular producer of documentation finishes shortly
before a higher priority one, like in the LSP engine Eglot as reported
by Andrii Kolomoiets <andreyk.mad@gmail.com> and Dmitry Gutov
<dgutov@yandex.ru>.

Gathering docstrings is now delegated to the variable
eldoc-documentation-strategy, which is the new name for the
now-obsolete eldoc-documentation-function, and still accepts the
so-called "old protocol".  Examples of the new strategies enabled are
codified in functions such as eldoc-documentation-enthusiast,
eldoc-documentation-compose-eagerly, along with the existing
eldoc-documentation-compose and eldoc-documentation-default.

The work of displaying and formatting docstrings is shifted almost
fully to Eldoc itself and is delegated to the internal function
eldoc--handle-docs.  Among other improvements, it handles most of
eldoc-echo-area-use-multiline-p and outputs documentation to a
temporary *eldoc* buffer.

The manual and NEWS are updated to mention the new Eldoc features.

* lisp/emacs-lisp/eldoc.el (eldoc-documentation-functions):
Overhaul docstring.
(eldoc-documentation-compose, eldoc-documentation-default): Handle
non-nil, non-string values of elements of
eldoc-documentation-functions.  Use eldoc--handle-multiline.
(eldoc-print-current-symbol-info): Honour non-nil, non-string
values returned by eldoc-documentation-callback.
(eldoc--make-callback): Now also a function.
(eldoc-documentation-default, eldoc-documentation-compose): Tweak docstring.
(eldoc-documentation-enthusiast, eldoc-documentation-compose-eagerly):
New functions.
(eldoc-echo-area-use-multiline-p): Add new semantics.
(eldoc--handle-docs): Handle some of eldoc-echo-area-use-multiline-p.
(eldoc-doc-buffer): New command.
(eldoc-prefer-doc-buffer): New defcustom.
(eldoc--enthusiasm-curbing-timer): New variable.
(eldoc-documentation-strategy): Rename from eldoc-documentation-function.
(eldoc--supported-p): Use eldoc-documentation-strategy
(eldoc-highlight-function-argument)
(eldoc-argument-case, global-eldoc-mode)
(turn-on-eldoc-mode): Mention eldoc-documentation-strategy.
(eldoc-message-function): Mention eldoc--message.
(eldoc-message): Made obsolete.
(eldoc--message): New helper.

* lisp/hexl.el (hexl-print-current-point-info): Adjust to new
eldoc-documentation-functions protocol.

* lisp/progmodes/cfengine.el (cfengine3-documentation-function):
Adjust to new eldoc-documentation-functions protocol.

* lisp/progmodes/elisp-mode.el
(elisp-eldoc-documentation-function): Adjust to new
eldoc-documentation-functions protocol.

* lisp/progmodes/octave.el (octave-eldoc-function): Adjust to new
eldoc-documentation-functions protocol.

* lisp/progmodes/python.el (python-eldoc-function): Adjust to new
eldoc-documentation-functions protocol.

(eldoc-print-current-symbol-info): Rework with cl-labels.

* doc/emacs/programs.texi (Lisp Doc): Mention
eldoc-documentation-strategy.

* doc/lispref/modes.texi (Major Mode Conventions): Mention
eldoc-documentation-functions.

* etc/NEWS: Mention eldoc-documentation-strategy.
2020-07-08 11:25:33 +01:00
..
charsets Update copyright year to 2020 2020-01-01 00:59:52 +00:00
e Prefer straight quoting in some etc text files 2015-08-26 14:09:07 -07:00
forms Use lexical-binding in forms.el example files 2020-04-25 07:59:28 +02:00
gnus
images Fix copyright years by hand 2020-01-01 01:01:53 +00:00
nxml Update nXML to use Emacs's Unicode support, and lexical-binding 2016-01-15 10:29:20 -05:00
org Update copyright year to 2020 2020-01-01 00:59:52 +00:00
refcards Merge from origin/emacs-27 2020-01-01 01:08:16 +00:00
schema Update copyright year to 2020 2020-01-01 00:59:52 +00:00
srecode Add and remove backslashes in regexps 2020-02-20 16:03:30 +01:00
themes Merge from origin/emacs-27 2020-05-16 10:29:14 -07:00
tutorials Fix copyright years by hand 2020-01-01 01:01:53 +00:00
AUTHORS ; Update etc/AUTHORS 2020-04-14 18:33:50 +02:00
CALC-NEWS Update copyright year to 2020 2020-01-01 00:59:52 +00:00
ChangeLog.1 Update copyright year to 2020 2020-01-01 00:59:52 +00:00
compilation.txt javac support in compilation-parse-errors rules 2020-04-01 03:04:31 +03:00
COPYING Merge from Gnulib 2017-10-01 18:31:10 -07:00
DEBUG ; bug#39779: Fix some typos in documentation. 2020-02-28 15:21:55 +02:00
DEVEL.HUMOR Remove an unfunny joke from DEVEL.HUMOR 2019-11-01 13:54:51 +01:00
DISTRIB Update copyright year to 2020 2020-01-01 00:59:52 +00:00
edt-user.el * etc/edt-user.el: Use lexical-binding. 2020-04-24 11:48:25 +02:00
emacs-buffer.gdb Update copyright year to 2020 2020-01-01 00:59:52 +00:00
emacs.appdata.xml Update copyright year to 2020 2020-01-01 00:59:52 +00:00
emacs.desktop
emacs.icon
emacs.service Don't override SSH_AUTH_SOCK in the example emacs.service file 2019-07-21 17:11:59 +02:00
enriched.txt Update copyright year to 2020 2020-01-01 00:59:52 +00:00
ERC-NEWS Update copyright year to 2020 2020-01-01 00:59:52 +00:00
ETAGS.EBNF Update copyright year to 2020 2020-01-01 00:59:52 +00:00
ETAGS.README Update copyright year to 2020 2020-01-01 00:59:52 +00:00
future-bug
gnus-tut.txt Update copyright year to 2020 2020-01-01 00:59:52 +00:00
grep.txt Update copyright year to 2020 2020-01-01 00:59:52 +00:00
HELLO Update copyright year to 2020 2020-01-01 00:59:52 +00:00
HISTORY * etc/HISTORY: Add Emacs 26.3 release release date. 2019-08-22 00:40:13 +02:00
JOKES
MACHINES Update copyright year to 2020 2020-01-01 00:59:52 +00:00
MH-E-NEWS Update copyright year to 2020 2020-01-01 00:59:52 +00:00
NEWS Better handle asynchronous Eldoc sources 2020-07-08 11:25:33 +01:00
NEWS.1-17 Update copyright year to 2020 2020-01-01 00:59:52 +00:00
NEWS.18 Update copyright year to 2020 2020-01-01 00:59:52 +00:00
NEWS.19 Update copyright year to 2020 2020-01-01 00:59:52 +00:00
NEWS.20 Update copyright year to 2020 2020-01-01 00:59:52 +00:00
NEWS.21 Update copyright year to 2020 2020-01-01 00:59:52 +00:00
NEWS.22 Update copyright year to 2020 2020-01-01 00:59:52 +00:00
NEWS.23 Update copyright year to 2020 2020-01-01 00:59:52 +00:00
NEWS.24 ; Fix NEWS.24 2020-01-01 18:30:58 +02:00
NEWS.25 * etc/NEWS.25: Belatedly announce upcase-dwim and downcase-dwim. 2020-05-27 14:09:23 -04:00
NEWS.26 Update copyright year to 2020 2020-01-01 00:59:52 +00:00
NEWS.27 Merge from origin/emacs-27 2020-06-17 08:47:53 -07:00
NEXTSTEP Update copyright year to 2020 2020-01-01 00:59:52 +00:00
NXML-NEWS Update copyright year to 2020 2020-01-01 00:59:52 +00:00
ORG-NEWS Update copyright year to 2020 2020-01-01 00:59:52 +00:00
package-keyring.gpg * etc/package-keyring.gpg: Add the 2019 key (backport) 2019-05-08 13:19:36 -04:00
PROBLEMS ; * etc/PROBLEMS: Add note about color list issues on macOS. 2020-05-20 21:25:01 +01:00
ps-prin0.ps Update copyright year to 2020 2020-01-01 00:59:52 +00:00
ps-prin1.ps Update copyright year to 2020 2020-01-01 00:59:52 +00:00
publicsuffix.txt Update publicsuffix.txt. 2016-02-06 16:11:18 +11:00
README Update copyright year to 2020 2020-01-01 00:59:52 +00:00
rgb.txt
ses-example.ses Update copyright year to 2020 2020-01-01 00:59:52 +00:00
spook.lines Add more spook.lines 2019-07-13 05:09:45 +02:00
TERMS Update copyright year to 2020 2020-01-01 00:59:52 +00:00
TODO ; * etc/TODO: Fix formatting. (Bug#41497) 2020-05-30 19:10:14 +03:00
yow.lines Prefer straight quoting in some etc text files 2015-08-26 14:09:07 -07:00

README 

This directory contains the architecture-independent files used by or
with Emacs.  This includes some text files of documentation for GNU
Emacs or of interest to Emacs users, and the file of dumped docstrings
for Emacs functions and variables.

COPYRIGHT AND LICENSE INFORMATION FOR IMAGE FILES

File: emacs.icon
  Author: Sun Microsystems, Inc
  Copyright (C) 1999, 2001-2020 Free Software Foundation, Inc.
  License: GNU General Public License version 3 or later (see COPYING)