From: Eli Zaretskii Date: Sun, 12 Mar 2023 08:25:10 +0000 (+0200) Subject: ; Fix last change X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=9191fd50d242cde5256b876dd756ffbc6f46db90;p=emacs.git ; Fix last change * lisp/emacs-lisp/shortdoc.el (shortdoc-help-fns-examples-function) (shortdoc-function-examples): Fix compilation warning and add an empty line before the examples. * lisp/emacs-lisp/shortdoc.el (shortdoc--insert-group-in-buffer) (shortdoc-function-examples) (shortdoc-help-fns-examples-function): * etc/NEWS: * doc/lispref/help.texi (Documentation Groups): * doc/emacs/help.texi (Name Help): Improve documentation of the last change. (Bug#61877) --- diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 10c007eb635..945e12a05d2 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -316,10 +316,11 @@ there's a doc string there. 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. -Here's an example you can include in your initialization file -(@pxref{Init File}) that uses @code{shortdoc} to insert Emacs Lisp -function examples into regular @file{*Help*} buffers when you use -@kbd{C-h f}: + +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 diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 3175f66122e..d5e4e1c31d3 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -995,23 +995,23 @@ shortdoc groups. @defun shortdoc-function-examples function This function returns all shortdoc examples for @var{function}. The -result is an alist with items of the form - -@example -(@var{group} . @var{examples}) -@end example - -@noindent -where @var{group} is a documentation group where @var{function} -appears in and @var{examples} is a string with the examples of use of -@var{function} defined in @var{group}. +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 contain shortdoc information. +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 documentation groups and inserts -examples of use of a given Emacs Lisp function into the current -buffer. +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 diff --git a/etc/NEWS b/etc/NEWS index 5f51b801774..e43aac614c9 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -224,15 +224,15 @@ This replaces 'doc-view-svg-foreground' and 'doc-view-svg-background'. +++ *** New function 'shortdoc-function-examples'. -This function queries the registered documentation groups and returns -examples of use of a given Emacs Lisp function. +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 queries the registered documentation groups and inserts -examples of use of a given Emacs Lisp function into the current -buffer. If you want to insert Emacs Lisp function examples into -regular *Help* buffers when you use 'describe-function', add the +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 diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el index cf66a43fc35..6e3ebc7c6a2 100644 --- a/lisp/emacs-lisp/shortdoc.el +++ b/lisp/emacs-lisp/shortdoc.el @@ -1455,7 +1455,8 @@ If SAME-WINDOW, don't pop to a new window." (beginning-of-line))) (defun shortdoc--insert-group-in-buffer (group &optional buf) - "Insert a short documentation summary for functions in GROUP in buffer 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)) @@ -1593,10 +1594,10 @@ function's documentation in the Info manual")) (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 in and +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 contain shortdoc information." +doesn't has any shortdoc information." (let ((groups (and (symbolp function) (shortdoc-function-groups function))) (examples nil)) @@ -1605,28 +1606,28 @@ doesn't contain shortdoc information." (with-temp-buffer (shortdoc--insert-group-in-buffer group) (goto-char (point-min)) - (setq 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))) + (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' list to show function -example documentation in *Help* buffers." +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 " Example:\n\n") - (insert " Examples:\n\n"))) + (insert "\n Example:\n\n") + (insert "\n Examples:\n\n"))) (setq times (1+ times)) (insert " ") (insert (cdr example))