mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-09 05:01:02 -08:00
Code Issues Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/master' into feature/android

Browse source
This commit is contained in:
Po Lu 2023-03-12 19:37:00 +08:00
commit 90c22cb949
6 changed files with 152 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

10
doc/emacs/help.texi
View file

@ -317,6 +317,16 @@ by using the @kbd{M-x shortdoc} command. This will prompt you for an
area of interest, e.g., @code{string}, and pop you to a buffer where
many of the functions relevant for handling strings are listed.
You can also request that documentation of functions and commands
shown in @file{*Help*} buffers popped by @kbd{C-h f} includes examples
of their use. To that end, add the following to your initialization
file (@pxref{Init File}):
@example
(add-hook 'help-fns-describe-function-functions
#'shortdoc-help-fns-examples-function)
@end example
@kindex C-h v
@findex describe-variable
@kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but

26
doc/lispref/help.texi
View file

@ -989,3 +989,29 @@ in the function group to insert the function into.
If @var{group} doesn't exist, it will be created. If @var{section}
doesn't exist, it will be added to the end of the function group.
@end defun
You can also query the examples of use of functions defined in
shortdoc groups.
@defun shortdoc-function-examples function
This function returns all shortdoc examples for @var{function}. The
return value is an alist with items of the form
@w{@code{(@var{group} . @var{examples})}}, where @var{group} is a
documentation group where @var{function} appears, and @var{examples}
is a string with the examples of @var{function}s use as defined in
@var{group}.
@code{shortdoc-function-examples} returns @code{nil} if @var{function}
is not a function or if it doesn't have any shortdoc examples.
@end defun
@vindex help-fns-describe-function-functions
@defun shortdoc-help-fns-examples-function function
This function queries the registered shortdoc groups and inserts
examples of use of a given Emacs Lisp @var{function} into the current
buffer. It is suitable for addition to the
@code{help-fns-describe-function-functions} hook, in which case
examples from shortdoc of using a function will be displayed in the
@file{*Help*} buffer when the documentation of the function is
requested.
@end defun

18
etc/NEWS
View file

@ -232,6 +232,24 @@ asynchronously (which is the default behavior).
*** New face 'doc-view-svg-face'.
This replaces 'doc-view-svg-foreground' and 'doc-view-svg-background'.
** Shortdoc
+++
*** New function 'shortdoc-function-examples'.
This function returns examples of use of a given Emacs Lisp function
from the available shortdoc information.
+++
*** New function 'shortdoc-help-fns-examples-function'.
This function inserts into the current buffer examples of use of a
given Emacs Lisp function, which it gleans from the shortdoc
information. If you want 'describe-function' ('C-h f') to insert
examples of using the function into regular *Help* buffers, add the
following to you init file:
(add-hook 'help-fns-describe-function-functions
#'shortdoc-help-fns-examples-function)
* New Modes and Packages in Emacs 30.1

123
lisp/emacs-lisp/shortdoc.el
View file

@ -1443,45 +1443,52 @@ If SAME-WINDOW, don't pop to a new window."
(setq group (intern group)))
(unless (assq group shortdoc--groups)
(error "No such documentation group %s" group))
(funcall (if same-window
#'pop-to-buffer-same-window
#'pop-to-buffer)
(format "*Shortdoc %s*" group))
(let ((inhibit-read-only t)
(prev nil))
(erase-buffer)
(shortdoc-mode)
(button-mode)
(mapc
(lambda (data)
(cond
((stringp data)
(setq prev nil)
(unless (bobp)
(insert "\n"))
(insert (propertize
(substitute-command-keys data)
'face 'shortdoc-heading
'shortdoc-section t
'outline-level 1))
(insert (propertize
"\n\n"
'face 'shortdoc-heading
'shortdoc-section t)))
;; There may be functions not yet defined in the data.
((fboundp (car data))
(when prev
(insert (make-separator-line)
;; This helps with hidden outlines (bug#53981)
(propertize "\n" 'face '(:height 0))))
(setq prev t)
(shortdoc--display-function data))))
(cdr (assq group shortdoc--groups))))
(let ((buf (get-buffer-create (format "*Shortdoc %s*" group))))
(shortdoc--insert-group-in-buffer group buf)
(funcall (if same-window
#'pop-to-buffer-same-window
#'pop-to-buffer)
buf))
(goto-char (point-min))
(when function
(text-property-search-forward 'shortdoc-function function t)
(beginning-of-line)))
(defun shortdoc--insert-group-in-buffer (group &optional buf)
"Insert a short documentation summary for functions in GROUP in buffer BUF.
BUF defaults to the current buffer if nil or omitted."
(with-current-buffer (or buf (current-buffer))
(let ((inhibit-read-only t)
(prev nil))
(erase-buffer)
(shortdoc-mode)
(button-mode)
(mapc
(lambda (data)
(cond
((stringp data)
(setq prev nil)
(unless (bobp)
(insert "\n"))
(insert (propertize
(substitute-command-keys data)
'face 'shortdoc-heading
'shortdoc-section t
'outline-level 1))
(insert (propertize
"\n\n"
'face 'shortdoc-heading
'shortdoc-section t)))
;; There may be functions not yet defined in the data.
((fboundp (car data))
(when prev
(insert (make-separator-line)
;; This helps with hidden outlines (bug#53981)
(propertize "\n" 'face '(:height 0))))
(setq prev t)
(shortdoc--display-function data))))
(cdr (assq group shortdoc--groups))))))
;;;###autoload
(defalias 'shortdoc #'shortdoc-display-group)
@ -1521,7 +1528,8 @@ function's documentation in the Info manual"))
"=>"))
(single-arrow (if (char-displayable-p ?→)
"→"
"->")))
"->"))
(start-example (point)))
(cl-loop for (type value) on data by #'cddr
do
(cl-case type
@ -1572,7 +1580,8 @@ function's documentation in the Info manual"))
(:eg-result-string
(insert " e.g. " double-arrow " ")
(princ value (current-buffer))
(insert "\n")))))
(insert "\n"))))
(add-text-properties start-example (point) `(shortdoc-example ,function)))
;; Insert the arglist after doing the evals, in case that's pulled
;; in the function definition.
(save-excursion
@ -1582,6 +1591,48 @@ function's documentation in the Info manual"))
(insert " " (symbol-name param)))
(add-face-text-property arglist-start (point) 'shortdoc-section t))))
(defun shortdoc-function-examples (function)
"Return all shortdoc examples for FUNCTION.
The result is an alist with items of the form (GROUP . EXAMPLES),
where GROUP is a shortdoc group where FUNCTION appears, and
EXAMPLES is a string with the usage examples of FUNCTION defined
in GROUP. Return nil if FUNCTION is not a function or if it
doesn't has any shortdoc information."
(let ((groups (and (symbolp function)
(shortdoc-function-groups function)))
(examples nil))
(mapc
(lambda (group)
(with-temp-buffer
(shortdoc--insert-group-in-buffer group)
(goto-char (point-min))
(let ((match (text-property-search-forward
'shortdoc-example function t)))
(push `(,group . ,(string-trim
(buffer-substring-no-properties
(prop-match-beginning match)
(prop-match-end match))))
examples))))
groups)
examples))
(defun shortdoc-help-fns-examples-function (function)
"Insert Emacs Lisp examples for FUNCTION into the current buffer.
You can add this function to the `help-fns-describe-function-functions'
hook to show examples of using FUNCTION in *Help* buffers produced
by \\[describe-function]."
(let ((examples (shortdoc-function-examples function))
(times 0))
(dolist (example examples)
(when (zerop times)
(if (eq (length examples) 1)
(insert "\n Example:\n\n")
(insert "\n Examples:\n\n")))
(setq times (1+ times))
(insert " ")
(insert (cdr example))
(insert "\n\n"))))
(defun shortdoc-function-groups (function)
"Return all shortdoc groups FUNCTION appears in."
(cl-loop for group in shortdoc--groups

10
test/lisp/emacs-lisp/shortdoc-tests.el
View file

@ -65,6 +65,16 @@
(when buf
(kill-buffer buf))))))
(ert-deftest shortdoc-function-examples-test ()
"Test the extraction of usage examples of some Elisp functions."
(should (equal '((list . "(delete 2 (list 1 2 3 4))\n => (1 3 4)\n (delete \"a\" (list \"a\" \"b\" \"c\" \"d\"))\n => (\"b\" \"c\" \"d\")"))
(shortdoc-function-examples 'delete)))
(should (equal '((alist . "(assq 'foo '((foo . bar) (zot . baz)))\n => (foo . bar)")
(list . "(assq 'b '((a . 1) (b . 2)))\n => (b . 2)"))
(shortdoc-function-examples 'assq)))
(should (equal '((regexp . "(string-match-p \"^[fo]+\" \"foobar\")\n => 0"))
(shortdoc-function-examples 'string-match-p))))
(provide 'shortdoc-tests)
;;; shortdoc-tests.el ends here

2
test/lisp/eshell/em-cmpl-tests.el
View file

@ -261,7 +261,7 @@ See <lisp/eshell/esh-var.el>."
"Test completion of things that look like variable assignment, but aren't.
For example, the second argument in \"tar --directory=dir\" looks
like it could be a variable assignment, but it's not. We should
let `pcomplete-tar' handle it instead.
let `pcomplete/tar' handle it instead.
See <lisp/eshell/esh-var.el>."
(with-temp-eshell