Elisp-mode was doing a lot of work that can now be delegated to Eldoc.
Flymake uses the new Eldoc functionality, too, installing a global
documentation function that may report on diagnostics under point.
CEDET's grammar.el was left as the only user of an Eldoc-internal
function. That function was moved to grammar.el. That file is still,
somewhat reprehensibly, using an internal function of elisp-mode.el,
but this was left unchanged.
In other situations, eldoc-documentation-functions is used or
recommended.
The only other places where the obsolete eldoc-documentation-function
is still used is in libraries which are presumably meant to remain
compatible with previous Emacs versions.
* lisp/progmodes/elisp-mode.el (elisp-eldoc-funcall)
(elisp-eldoc-var-docstring): New functions.
(emacs-lisp-mode): Put two elements in
eldoc-documentation-functions.
* lisp/emacs-lisp/eldoc.el (eldoc--eval-expression-setup): Setup
new Elisp eldoc-documentation-functions.
* lisp/progmodes/flymake.el (flymake-mode): Use
flymake-eldoc-function.
(flymake-eldoc-function): New function.
(Package-Requires): Require eldoc 1.1.0
* lisp/descr-text.el (describe-char-eldoc): Recommend
eldoc-documentation-functions.
* lisp/progmodes/cfengine.el (cfengine3-documentation-function):
Recommend eldoc-documentation-functions
* lisp/progmodes/octave.el (inferior-octave-mode): Use
eldoc-documentation-functions.
* lisp/cedet/semantic/grammar.el (semantic--docstring-format-sym-doc):
New function.
(semantic-grammar-eldoc-get-macro-docstring): Adjust.
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.
* lisp/emacs-lisp/eldoc.el: Update commentary.
(eldoc--eval-expression-setup): Use new hook.
(eldoc--supported-p): Accomodate new hook.
(eldoc-documentation-functions): New hook.
(eldoc-documentation-default, eldoc-documentation-compose): New
functions.
(eldoc-documentation-function): Use 'eldoc-documentation-default' as new
default value. Update documentation and custom attributes.
(eldoc-print-current-symbol-info): Accomodate possible null value for
'eldoc-documentation-function'.
* etc/NEWS: Mention them.
* doc/emacs/programs.texi (Emacs Lisp Documentation Lookup): Mention
new hook and changes to 'eldoc-documentation-function'.
* lisp/hexl.el (hexl-mode, hexl-revert-buffer-function):
* lisp/ielm.el (inferior-emacs-lisp-mode):
* lisp/progmodes/cfengine.el (cfengine3-mode):
* lisp/progmodes/elisp-mode.el (emacs-lisp-mode):
* lisp/progmodes/octave.el (octave-mode):
* lisp/progmodes/python.el (python-mode): Use new hook.
Most of this change is to boilerplate commentary such as license URLs.
This change was prompted by ftp://ftp.gnu.org's going-away party,
planned for November. Change these FTP URLs to https://ftp.gnu.org
instead. Make similar changes for URLs to other organizations moving
away from FTP. Also, change HTTP to HTTPS for URLs to gnu.org and
fsf.org when this works, as this will further help defend against
man-in-the-middle attacks (for this part I omitted the MS-DOS and
MS-Windows sources and the test tarballs to keep the workload down).
HTTPS is not fully working to lists.gnu.org so I left those URLs alone
for now.
This patch should not change behavior. It typically omits backslashes
where they are redundant (e.g., in the string literal "^\$").
In a few places, insert backslashes where they make regular
expressions clearer: e.g., replace "^\*" (equivalent to "^*") with
"^\\*", which has the same effect as a regular expression.
Also, use ‘\ %’ instead of ‘\%’ when avoiding confusion with SCCS IDs,
and similarly use ‘\ $’ instead of ‘\$’ when avoiding confusion with
RCS IDs, as that makes it clearer that the backslash is intended.
Update for the upcoming CFEngine 3.7 release: support macros and
quoted context strings; reformat JSON; indent promise attributes 2
units by default; give function parameter descriptions in the eldoc
glue.
* cfengine.el: Update version and docs and fix name. Autoload
`json-pretty-print'. Support new features in 3.7.
(cfengine-parameters-indent): Set default promise attribute indent to
2 more than the promise itself.
(cfengine3-macro-regex): New variable to match the new macro syntax.
(cfengine3-font-lock-keywords): Use it to highlight macros.
(cfengine3-indent-line): Use it to indent macros to column 0.
(cfengine3-class-selector-regex): Update for the new quoted strings
format.
(cfengine3-reformat-json-string): New function to reformat a JSON
string using `json-pretty-print'.
(cfengine3-format-function-docstring): Use function parameter
description if it's provided by the cf-promises syntax dump.
* lisp/emacs-lisp/eldoc.el (eldoc-documentation-function): Describe how
major modes should use `add-function' to alter value of the variable.
* lisp/hexl.el (hexl-mode): Set `eldoc-documentation-function' using
`add-function' so the default value is always used.
* lisp/ielm.el (inferior-emacs-lisp-mode): Set
`eldoc-documentation-function' using `add-function' so the default
value is always used.
* lisp/progmodes/cfengine.el (cfengine3-mode): Set
`eldoc-documentation-function' using `add-function' so the default
value is always used.
* lisp/progmodes/elisp-mode (emacs-lisp-mode): Set
`eldoc-documentation-function' using `add-function' so the default
value is always used.
* lisp/progmodes/octave.el (octave-mode): Set
`eldoc-documentation-function' using `add-function' so the default
value is always used.
* lisp/progmodes/python.el (python-mode): Set
`eldoc-documentation-function' using `add-function' so the default
value is always used.
* lisp/simple.el (read--expression): Set `eldoc-documentation-function'
using `add-function' so the default value is always used.
(cfengine3-create-imenu-index): Use it and use ` ' for separation.
(cfengine3-current-defun): New function.
(cfengine3-mode): Set add-log-current-defun-function.
Use strings.
(cfengine3-create-imenu-index): New function.
(cfengine3-mode): Use it for `imenu-create-index-function'.
(cfengine-auto-mode): Improve and prefer cfengine3-mode when
buffer is empty.
return a syntax. Replace call-process-shell-command with
process-file. Ensure cfengine-mode-syntax-functions-regex is
always set. Ensure cache when cfengine-cf-promises fails.
Fixes: debbugs:18620
* progmodes/cfengine.el (cfengine3--current-word): Remove.
(cfengine3--current-function): Bring in the current-function
functionality from `cfengine3--current-word'.
(cfengine3-completion-function): Bring in the
bounds-of-current-word functionality from
`cfengine3--current-word'.
* progmodes/cfengine.el (cfengine-cf-promises): Add more default
locations for cf-promises.
(cfengine-mode-syntax-functions-regex): New caching variable.
(cfengine3-fallback-syntax): Fallback syntax for cases where
cf-promises doesn't run.
(cfengine3--current-word): Reimplement using
`cfengine-mode-syntax-functions-regex'.
(cfengine3-completion-function, cfengine3--current-function): Use
`cfengine3-make-syntax-cache' directly.
(cfengine3-clear-syntax-cache): New function.
(cfengine3-make-syntax-cache): Simplify and create
`cfengine-mode-syntax-functions-regex' on demand.
(cfengine3-format-function-docstring): Don't call
`cfengine3-make-syntax-cache' explicitly.
* progmodes/cfengine.el: Version bump.
(cfengine-cf-promises): New defcustom to locate cf-promises.
(cfengine3-vartypes): Add new "data" type.
(cfengine3--current-word): New function to get current name-like
word or its bounds.
(cfengine3--current-function): New function to look up a CFEngine
function's definition.
(cfengine3-format-function-docstring): New function.
(cfengine3-make-syntax-cache): New function.
(cfengine3-documentation-function): New function: ElDoc glue.
(cfengine3-completion-function): New function: completion glue.
(cfengine3-mode): Set `compile-command',
`eldoc-documentation-function', and add to
`completion-at-point-functions'.
* etc/NEWS: Document new Prettify Symbols mode.
* lisp/progmodes/prog-mode.el (prettify-symbols-alist): Rename from
`prog-prettify-symbols', and make a local defvar instead of defcustom.
(prettify-symbols--keywords): Rename from `prog-prettify-symbols-alist'
and make a local defvar.
(prettify-symbols--compose-symbol): Rename from
`prog--prettify-font-lock-compose-symbol'.
(prettify-symbols--make-keywords): Rename from
`prog-prettify-font-lock-symbols-keywords' and simplify.
(prog-prettify-install): Remove.
(prettify-symbols-mode): New minor mode, based on `prog-prettify-install'.
(turn-on-prettify-symbols-mode): New function.
(global-prettify-symbols-mode): New globalized minor mode.
* lisp/emacs-lisp/lisp-mode.el (lisp-mode-variables):
* lisp/progmodes/cfengine.el (cfengine3-mode):
* lisp/progmodes/perl-mode.el (perl-mode): Don't call `prog-prettify-install';
set `prettify-symbols-alist' instead.
