emacs/doc/lispref, branch scratch/python-eldoc-async Emacs is the extensible, customizable, self-documenting real-time display editor. Better handle asynchronous Eldoc sources 2020-07-08T10:25:33+00:00 João Távora 2020-05-25T15:39:40+00:00 a7a53f0d79e0012c909e87911c4f85ad12bb78b4 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. 
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.
Merge from origin/emacs-27 2020-07-07T14:50:40+00:00 Glenn Morris 2020-07-07T14:50:40+00:00 1a850f4b20d11938d68270147d3d5ebc3c4899f4 71fc003860 (origin/emacs-27) Avoid infloop in 'format-mode-line' 247dcb4b1b Clarify the documentation of 'left/right-fringe' display spec d453cee177 Minor improvement in ELisp manual 3c778c443c * doc/misc/tramp.texi (Customizing Methods): Fix typo. 
71fc003860 (origin/emacs-27) Avoid infloop in 'format-mode-line'
247dcb4b1b Clarify the documentation of 'left/right-fringe' display spec
d453cee177 Minor improvement in ELisp manual
3c778c443c * doc/misc/tramp.texi (Customizing Methods): Fix typo.
Clarify the documentation of 'left/right-fringe' display spec 2020-07-05T15:30:21+00:00 Eli Zaretskii 2020-07-05T15:30:21+00:00 247dcb4b1b1b4ea3d50b63d41c4efa58743f610d * doc/lispref/display.texi (Other Display Specs, Fringe Bitmaps): Clarify how the optional FACE parameter of the left-fringe and right-fringe display spec is used. Reported by Gregory Heytings <ghe@sdf.org>. 
* doc/lispref/display.texi (Other Display Specs, Fringe Bitmaps):
Clarify how the optional FACE parameter of the left-fringe and
right-fringe display spec is used.  Reported by Gregory Heytings
<ghe@sdf.org>.
Minor improvement in ELisp manual 2020-07-04T07:19:56+00:00 Eli Zaretskii 2020-07-04T07:19:56+00:00 d453cee1773a27d9d30fac18de0f32e5a08d3294 * doc/lispref/frames.texi (Position Parameters): Clarify the description of the 'above' frame parameter. (Bug#42154) 
* doc/lispref/frames.texi (Position Parameters): Clarify the
description of the 'above' frame parameter.  (Bug#42154)
Use getrandom syscall for nonces 2020-06-27T20:03:49+00:00 Paul Eggert 2020-06-27T20:02:24+00:00 5ce5cf643840cd6efd25d987bc5b6f12478c50a6 * admin/merge-gnulib (GNULIB_MODULES): Add getrandom. * doc/lispref/text.texi (Format of GnuTLS Cryptography Inputs): Don’t say that iv-auto uses GNUTLS_RND_NONCE. Also, don’t say that it returns the IV’s actual value, as it never has done that. * src/fns.c, src/sysdep.c: Include sys/random.h, for getrandom. * src/fns.c (Fsecure_hash_algorithms): Use getrandom so that this function does not depend on HAVE_GNUTLS3. * src/sysdep.c: Do not include <gnutls/crypto.h>. (random_seed) [HAVE_LRAND48]: Can be long int now. (init_random) [!WINDOWSNT]: Use getrandom syscall instead of opening /dev/urandom, as this works even on GNU/Linux hosts that lack /dev/urandom. Don’t bother with gnutls_rnd as it’s not needed now that we have getrandom. 
* admin/merge-gnulib (GNULIB_MODULES): Add getrandom.
* doc/lispref/text.texi (Format of GnuTLS Cryptography Inputs):
Don’t say that iv-auto uses GNUTLS_RND_NONCE.  Also, don’t say
that it returns the IV’s actual value, as it never has done that.
* src/fns.c, src/sysdep.c: Include sys/random.h, for getrandom.
* src/fns.c (Fsecure_hash_algorithms): Use getrandom so that this
function does not depend on HAVE_GNUTLS3.
* src/sysdep.c: Do not include <gnutls/crypto.h>.
(random_seed) [HAVE_LRAND48]: Can be long int now.
(init_random) [!WINDOWSNT]: Use getrandom syscall instead
of opening /dev/urandom, as this works even on GNU/Linux
hosts that lack /dev/urandom.  Don’t bother with gnutls_rnd
as it’s not needed now that we have getrandom.
Merge from origin/emacs-27 2020-06-26T14:50:38+00:00 Glenn Morris 2020-06-26T14:50:38+00:00 ffb89ed5f07491e33fc79d8b4be49d9deba2ad4a 5280e118c0 (origin/emacs-27) ; * src/xdisp.c (pos_visible_p): Fix las... bb1a9481c9 Fix posn-at-point at beginning of a display string 0c4b033670 Improve documentation of Info node movement commands 632b0119e1 Add Jansson dependency to Windows Build dbfcdab837 Unbreak 'reverse-region' c37de84845 Fix typos and markup in fill column indicator docs f61bff3ee9 ; * CONTRIBUTE: Clarify the preferences for patch formatting. 368e140660 Avoid crashes in 'defconst' 11e3413cff Fix text about Lisp archives in the Emacs FQ 4c81724675 Don't use 'cl' functions in ELisp manual's examples 
5280e118c0 (origin/emacs-27) ; * src/xdisp.c (pos_visible_p): Fix las...
bb1a9481c9 Fix posn-at-point at beginning of a display string
0c4b033670 Improve documentation of Info node movement commands
632b0119e1 Add Jansson dependency to Windows Build
dbfcdab837 Unbreak 'reverse-region'
c37de84845 Fix typos and markup in fill column indicator docs
f61bff3ee9 ; * CONTRIBUTE: Clarify the preferences for patch formatting.
368e140660 Avoid crashes in 'defconst'
11e3413cff Fix text about Lisp archives in the Emacs FQ
4c81724675 Don't use 'cl' functions in ELisp manual's examples
Don't use 'cl' functions in ELisp manual's examples 2020-06-20T07:29:37+00:00 Eli Zaretskii 2020-06-20T07:29:37+00:00 4c8172467533d70e6d2d0a58f527a84a7e59355a * doc/lispref/control.texi (pcase Macro): Use 'cl-evenp' instead of 'evenp'. (Bug#41947) 
* doc/lispref/control.texi (pcase Macro): Use 'cl-evenp' instead
of 'evenp'.  (Bug#41947)
Fix and extend format-spec (bug#41758) 2020-06-18T11:46:21+00:00 Basil L. Contovounesios 2020-05-29T18:56:14+00:00 0185d76e7426eb1b58a9b60b0d18e763ddf57dea * lisp/format-spec.el: Use lexical-binding. Remove dependence on subr-x.el. (format-spec-make): Clarify docstring. (format-spec--parse-modifiers): Rename to... (format-spec--parse-flags): ...this and simplify. In particular, don't bother parsing :space-pad which is redundant and unused. (format-spec--pad): Remove, replacing with... (format-spec--do-flags): ...this new helper function which performs more of format-spec's supported text manipulation. (format-spec): Autoload. Allow optional argument to take on special values 'ignore' and 'delete' for more control over what happens when a replacement for a format specification isn't provided. Bring back proper support for a precision modifier similar to that of 'format'. * lisp/battery.el (battery-format): Rewrite in terms of format-spec. (battery-echo-area-format, battery-mode-line-format): Mention support of format-spec syntax in docstrings. * doc/lispref/strings.texi (Custom Format Strings): * etc/NEWS: Document and announce these changes. * lisp/dired-aux.el (dired-do-compress-to): * lisp/erc/erc-match.el (erc-log-matches): * lisp/erc/erc.el (erc-update-mode-line-buffer): * lisp/gnus/gnus-sieve.el (gnus-sieve-update): * lisp/gnus/gssapi.el (open-gssapi-stream): * lisp/gnus/mail-source.el (mail-source-fetch-file) (mail-source-fetch-directory, mail-source-fetch-pop) (mail-source-fetch-imap): * lisp/gnus/message.el (message-insert-formatted-citation-line): * lisp/image-dired.el: * lisp/net/eww.el: * lisp/net/imap.el (imap-kerberos4-open, imap-gssapi-open) (imap-shell-open): * lisp/net/network-stream.el (network-stream-open-shell): * lisp/obsolete/tls.el (open-tls-stream): * lisp/textmodes/tex-mode.el: Remove extraneous loads and autoloads of format-spec now that it is autoloaded and simplify its uses where possible. * test/lisp/battery-tests.el (battery-format): Test new format-spec support. * test/lisp/format-spec-tests.el (test-format-spec): Rename to... (format-spec) ...this, extending test cases. (test-format-unknown): Rename to... (format-spec-unknown): ...this, extending test cases. (test-format-modifiers): Rename to... (format-spec-flags): ...this. (format-spec-make, format-spec-parse-flags, format-spec-do-flags) (format-spec-do-flags-truncate, format-spec-do-flags-pad) (format-spec-do-flags-chop, format-spec-do-flags-case): New tests. 
* lisp/format-spec.el: Use lexical-binding.  Remove dependence on
subr-x.el.
(format-spec-make): Clarify docstring.
(format-spec--parse-modifiers): Rename to...
(format-spec--parse-flags): ...this and simplify.  In particular,
don't bother parsing :space-pad which is redundant and unused.
(format-spec--pad): Remove, replacing with...
(format-spec--do-flags): ...this new helper function which performs
more of format-spec's supported text manipulation.
(format-spec): Autoload.  Allow optional argument to take on special
values 'ignore' and 'delete' for more control over what happens when
a replacement for a format specification isn't provided.  Bring back
proper support for a precision modifier similar to that of 'format'.

* lisp/battery.el (battery-format): Rewrite in terms of format-spec.
(battery-echo-area-format, battery-mode-line-format): Mention
support of format-spec syntax in docstrings.

* doc/lispref/strings.texi (Custom Format Strings):
* etc/NEWS: Document and announce these changes.

* lisp/dired-aux.el (dired-do-compress-to):
* lisp/erc/erc-match.el (erc-log-matches):
* lisp/erc/erc.el (erc-update-mode-line-buffer):
* lisp/gnus/gnus-sieve.el (gnus-sieve-update):
* lisp/gnus/gssapi.el (open-gssapi-stream):
* lisp/gnus/mail-source.el (mail-source-fetch-file)
(mail-source-fetch-directory, mail-source-fetch-pop)
(mail-source-fetch-imap):
* lisp/gnus/message.el (message-insert-formatted-citation-line):
* lisp/image-dired.el:
* lisp/net/eww.el:
* lisp/net/imap.el (imap-kerberos4-open, imap-gssapi-open)
(imap-shell-open):
* lisp/net/network-stream.el (network-stream-open-shell):
* lisp/obsolete/tls.el (open-tls-stream):
* lisp/textmodes/tex-mode.el:
Remove extraneous loads and autoloads of format-spec now that it is
autoloaded and simplify its uses where possible.

* test/lisp/battery-tests.el (battery-format): Test new format-spec
support.
* test/lisp/format-spec-tests.el (test-format-spec): Rename to...
(format-spec) ...this, extending test cases.
(test-format-unknown): Rename to...
(format-spec-unknown): ...this, extending test cases.
(test-format-modifiers): Rename to...
(format-spec-flags): ...this.
(format-spec-make, format-spec-parse-flags, format-spec-do-flags)
(format-spec-do-flags-truncate, format-spec-do-flags-pad)
(format-spec-do-flags-chop, format-spec-do-flags-case): New tests.
Merge from origin/emacs-27 2020-06-17T15:47:53+00:00 Glenn Morris 2020-06-17T15:47:53+00:00 21b03faed44913ba0b0e3d54d2ffdb0ac067fae8 229995ba2c (origin/emacs-27) Fix some Texinfo markup 01e86b9fdf Fix recentf typo in Emacs manual cd4f75bb86 Rename default function to next-error-buffer-unnavigated-c... 1dff0a8949 * lisp/image-mode.el (image-toggle-display-image): Fix fit... a71d1787f1 * doc/misc/tramp.texi (Predefined connection information):... 079b0dc430 Delete, don't kill, dir dir fragments in icomplete-fido-ba... 6cdecc2659 Revert markup change in with-coding-priority docs 22f4fba8a9 * lisp/emulation/cua-rect.el (cua--rectangle-region-insert... 6b9eac6759 * lisp/simple.el (shell-command-on-region): Fix docstring. 43ad7dc1af Clean up D-Bus documentation (bug#41744) c43e5ed60d * lisp/image-mode.el (image-transform-original): New comma... 6eb18a950d Move tab-bar and tab-line faces to faces.el (part of bug#4... # Conflicts: # etc/NEWS # lisp/simple.el 
229995ba2c (origin/emacs-27) Fix some Texinfo markup
01e86b9fdf Fix recentf typo in Emacs manual
cd4f75bb86 Rename default function to next-error-buffer-unnavigated-c...
1dff0a8949 * lisp/image-mode.el (image-toggle-display-image): Fix fit...
a71d1787f1 * doc/misc/tramp.texi (Predefined connection information):...
079b0dc430 Delete, don't kill, dir dir fragments in icomplete-fido-ba...
6cdecc2659 Revert markup change in with-coding-priority docs
22f4fba8a9 * lisp/emulation/cua-rect.el (cua--rectangle-region-insert...
6b9eac6759 * lisp/simple.el (shell-command-on-region): Fix docstring.
43ad7dc1af Clean up D-Bus documentation (bug#41744)
c43e5ed60d * lisp/image-mode.el (image-transform-original): New comma...
6eb18a950d Move tab-bar and tab-line faces to faces.el (part of bug#4...

# Conflicts:
#	etc/NEWS
#	lisp/simple.el
Fix some Texinfo markup 2020-06-17T12:07:51+00:00 Basil L. Contovounesios 2020-06-17T11:53:40+00:00 229995ba2cd9f6d0a749a38c106cbfbfd04119a8 * doc/misc/gnus-faq.texi (FAQ 3-11): * doc/emacs/frames.texi (Tab Bars): Consistently use @var with lower-case metasyntactic variables and @minus instead of a dash. (Text-Only Mouse): * doc/emacs/files.texi (Auto Revert): * doc/emacs/misc.texi (emacsclient Options) (Embedded WebKit Widgets): * doc/lispref/control.texi (pcase Macro): * doc/lispref/debugging.texi (Backtraces): * doc/lispref/files.texi (Truenames): * doc/lispref/frames.texi (Management Parameters): * doc/lispref/os.texi (Time Calculations): * doc/lispref/text.texi (Parsing JSON): * doc/misc/efaq-w32.texi (Other versions of Emacs, Debugging) (Swap Caps NT, Printing, Bash, Developing with Emacs): * doc/misc/efaq.texi (New in Emacs 25): * doc/misc/emacs-gnutls.texi (Help For Users): * doc/misc/message.texi (Using S/MIME, Passphrase caching): * test/manual/etags/tex-src/gzip.texi (Overview): Use @. when a sentence in the middle of a paragraph ends with an upper-case letter as per "(texinfo) Ending a Sentence". 
* doc/misc/gnus-faq.texi (FAQ 3-11):
* doc/emacs/frames.texi (Tab Bars): Consistently use @var with
lower-case metasyntactic variables and @minus instead of a dash.
(Text-Only Mouse):
* doc/emacs/files.texi (Auto Revert):
* doc/emacs/misc.texi (emacsclient Options)
(Embedded WebKit Widgets):
* doc/lispref/control.texi (pcase Macro):
* doc/lispref/debugging.texi (Backtraces):
* doc/lispref/files.texi (Truenames):
* doc/lispref/frames.texi (Management Parameters):
* doc/lispref/os.texi (Time Calculations):
* doc/lispref/text.texi (Parsing JSON):
* doc/misc/efaq-w32.texi (Other versions of Emacs, Debugging)
(Swap Caps NT, Printing, Bash, Developing with Emacs):
* doc/misc/efaq.texi (New in Emacs 25):
* doc/misc/emacs-gnutls.texi (Help For Users):
* doc/misc/message.texi (Using S/MIME, Passphrase caching):
* test/manual/etags/tex-src/gzip.texi (Overview): Use @. when a
sentence in the middle of a paragraph ends with an upper-case letter
as per "(texinfo) Ending a Sentence".