From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 7 Apr 2024 13:41:34 -0500 Subject: new repository --- devdocs/elisp/documentation-groups.html | 63 +++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 devdocs/elisp/documentation-groups.html (limited to 'devdocs/elisp/documentation-groups.html') diff --git a/devdocs/elisp/documentation-groups.html b/devdocs/elisp/documentation-groups.html new file mode 100644 index 00000000..92dd0787 --- /dev/null +++ b/devdocs/elisp/documentation-groups.html @@ -0,0 +1,63 @@ +

Documentation Groups

Emacs can list functions based on various groupings. For instance, string-trim and mapconcat are “string” functions, so M-x shortdoc-display-group RET string RET will give an overview of functions that operate on strings.

The documentation groups are created with the define-short-documentation-group macro.

Macro: define-short-documentation-group group &rest functions +
+

Define group as a group of functions, and provide short summaries of using those functions. The optional argument functions is a list whose elements are of the form: 

(func [keyword val]…)
+
+

The following keywords are recognized:

:eval
+

The value should be a form that has no side effect when evaluated. The form will be used in the documentation by printing it with prin1 (see Output Functions). However, if the form is a string, it will be inserted as-is, and the string will then be read to yield the form. In any case, the form will then be evaluated, and the result used. For instance: 

:eval (concat "foo" "bar" "zot")
+:eval "(make-string 5 ?x)"
+
+

will result in: 

(concat "foo" "bar" "zot")
+⇒ "foobarzot"
+(make-string 5 ?x)
+⇒ "xxxxx"
+
+

(The reason for allowing both Lisp forms and strings here is so that printing could be controlled in the few cases where a certain presentation of the form is wished for. In the example, ‘?x’ would otherwise have been printed as ‘120’ if it hadn’t been included in a string.)

:no-eval

This is like :eval, except that the form will not be evaluated. In these cases, a :result element of some kind (see below) should be included. 

:no-eval (file-symlink-p "/tmp/foo")
+:eg-result t
+
+
:no-eval*
+

Like :no-eval, but always inserts ‘[it depends]’ as the result. For instance: 

:no-eval* (buffer-string)
+
+

will result in: 

(buffer-string)
+→ [it depends]
+
+
:no-value
+

Like :no-eval, but is used when the function in question has no well-defined return value, and is used for side effect only.

:result
+

Used to output the result from non-evaluating example forms. 

:no-eval (setcar list 'c)
+:result c
+
+
:eg-result
+

Used to output an example result from non-evaluating example forms. For instance: 

:no-eval (looking-at "f[0-9]")
+:eg-result t
+
+

will result in: 

(looking-at "f[0-9]")
+eg. → t
+
+
:result-string
:eg-result-string
+

These two are the same as :result and :eg-result, respectively, but are inserted as is. This is useful when the result is unreadable or should be of a particular form: 

:no-eval (find-file "/tmp/foo")
+:eg-result-string "#<buffer foo>"
+:no-eval (default-file-modes)
+:eg-result-string "#o755"
+
+
:no-manual
+

Indicates that this function is not documented in the manual.

:args
+

By default, the function’s actual argument list is shown. If :args is present, they are used instead. 

:args (regexp string)
+
+

Here’s a very short example: 

(define-short-documentation-group string
+  "Creating Strings"
+  (substring
+   :eval (substring "foobar" 0 3)
+   :eval (substring "foobar" 3))
+  (concat
+   :eval (concat "foo" "bar" "zot")))
+
+

The first argument is the name of the group to be defined, and then follows any number of function descriptions.

+

A function can belong to any number of documentation groups.

In addition to function descriptions, the list can also have string elements, which are used to divide a documentation group into sections.

Function: shortdoc-add-function shortdoc-add-function group section elem +
+

Lisp packages can add functions to groups with this command. Each elem should be a function description, as described above. group is the function group, and section is what section in the function group to insert the function into.

If group doesn’t exist, it will be created. If section doesn’t exist, it will be added to the end of the function group.

+
+
+

+ Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc.
Licensed under the GNU GPL license.
+ https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Groups.html +

+
-- cgit v1.2.3