mirror of
git://git.sv.gnu.org/emacs.git
synced 2026-01-04 02:51:31 -08:00
a7a53f0d79
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. |
||
|---|---|---|
| .. | ||
| abbrevs.texi | ||
| anti.texi | ||
| back.texi | ||
| backups.texi | ||
| book-spine.texi | ||
| buffers.texi | ||
| ChangeLog.1 | ||
| commands.texi | ||
| compile.texi | ||
| control.texi | ||
| customize.texi | ||
| debugging.texi | ||
| display.texi | ||
| doclicense.texi | ||
| edebug.texi | ||
| elisp.texi | ||
| errors.texi | ||
| eval.texi | ||
| files.texi | ||
| frames.texi | ||
| functions.texi | ||
| gpl.texi | ||
| hash.texi | ||
| help.texi | ||
| hooks.texi | ||
| index.texi | ||
| internals.texi | ||
| intro.texi | ||
| keymaps.texi | ||
| lay-flat.texi | ||
| lists.texi | ||
| loading.texi | ||
| macros.texi | ||
| Makefile.in | ||
| maps.texi | ||
| markers.texi | ||
| minibuf.texi | ||
| modes.texi | ||
| nonascii.texi | ||
| numbers.texi | ||
| objects.texi | ||
| os.texi | ||
| package.texi | ||
| positions.texi | ||
| processes.texi | ||
| README | ||
| records.texi | ||
| searching.texi | ||
| sequences.texi | ||
| spellfile | ||
| streams.texi | ||
| strings.texi | ||
| symbols.texi | ||
| syntax.texi | ||
| text.texi | ||
| threads.texi | ||
| tips.texi | ||
| two-volume-cross-refs.txt | ||
| two-volume.make | ||
| variables.texi | ||
| windows.texi | ||
Copyright (C) 2001-2020 Free Software Foundation, Inc. -*- outline -*-
See the end of the file for license conditions.
README for the Emacs Lisp Reference Manual.
* This directory contains the texinfo source files for the Emacs Lisp
Reference Manual.
* Report bugs in the Lisp Manual (or in Emacs) using M-x report-emacs-bug.
To ask questions, use the help-gnu-emacs mailing list.
* The Emacs Lisp Reference Manual is quite large. It totals around
1100 pages in smallbook format; the info files total around 3.0 megabytes.
* You can format this manual for Info, for printing hardcopy using TeX,
or for HTML.
* You can buy nicely printed copies from the Free Software Foundation.
Buying a manual from the Free Software Foundation helps support our GNU
development work. See <https://shop.fsf.org/>.
(At time of writing, this manual is out of print.)
* The master file for formatting this manual for Tex is called 'elisp.texi'.
It contains @include commands to include all the chapters that make up
the manual.
* This distribution contains a Makefile that you can use with GNU Make.
** To make an Info file, you need to install Texinfo, then run 'make info'.
** Use 'make elisp.pdf' or 'make elisp.html' to create PDF or HTML versions.
This file is part of GNU Emacs.
GNU Emacs is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.