1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
|
<h3 class="section">Documentation Groups</h3> <p>Emacs can list functions based on various groupings. For instance, <code>string-trim</code> and <code>mapconcat</code> are “string” functions, so <kbd>M-x shortdoc-display-group RET string RET</kbd> will give an overview of functions that operate on strings. </p> <p>The documentation groups are created with the <code>define-short-documentation-group</code> macro. </p> <dl> <dt id="define-short-documentation-group">Macro: <strong>define-short-documentation-group</strong> <em>group &rest functions</em>
</dt> <dd>
<p>Define <var>group</var> as a group of functions, and provide short summaries of using those functions. The optional argument <var>functions</var> is a list whose elements are of the form: </p> <div class="lisp"> <pre class="lisp">(<var>func</var> [<var>keyword</var> <var>val</var>]…)
</pre>
</div> <p>The following keywords are recognized: </p> <dl compact> <dt><code>:eval</code></dt> <dd>
<p>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 <code>prin1</code> (see <a href="output-functions">Output Functions</a>). However, if the form is a string, it will be inserted as-is, and the string will then be <code>read</code> to yield the form. In any case, the form will then be evaluated, and the result used. For instance: </p> <div class="example"> <pre class="example">:eval (concat "foo" "bar" "zot")
:eval "(make-string 5 ?x)"
</pre>
</div> <p>will result in: </p> <div class="example"> <pre class="example">(concat "foo" "bar" "zot")
⇒ "foobarzot"
(make-string 5 ?x)
⇒ "xxxxx"
</pre>
</div> <p>(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, ‘<samp>?x</samp>’ would otherwise have been printed as ‘<samp>120</samp>’ if it hadn’t been included in a string.) </p> </dd> <dt><code>:no-eval</code></dt> <dd> <p>This is like <code>:eval</code>, except that the form will not be evaluated. In these cases, a <code>:result</code> element of some kind (see below) should be included. </p> <div class="example"> <pre class="example">:no-eval (file-symlink-p "/tmp/foo")
:eg-result t
</pre>
</div> </dd> <dt><code>:no-eval*</code></dt> <dd>
<p>Like <code>:no-eval</code>, but always inserts ‘<samp>[it depends]</samp>’ as the result. For instance: </p> <div class="example"> <pre class="example">:no-eval* (buffer-string)
</pre>
</div> <p>will result in: </p> <div class="example"> <pre class="example">(buffer-string)
→ [it depends]
</pre>
</div> </dd> <dt><code>:no-value</code></dt> <dd>
<p>Like <code>:no-eval</code>, but is used when the function in question has no well-defined return value, and is used for side effect only. </p> </dd> <dt><code>:result</code></dt> <dd>
<p>Used to output the result from non-evaluating example forms. </p> <div class="example"> <pre class="example">:no-eval (setcar list 'c)
:result c
</pre>
</div> </dd> <dt><code>:eg-result</code></dt> <dd>
<p>Used to output an example result from non-evaluating example forms. For instance: </p> <div class="example"> <pre class="example">:no-eval (looking-at "f[0-9]")
:eg-result t
</pre>
</div> <p>will result in: </p> <div class="example"> <pre class="example">(looking-at "f[0-9]")
eg. → t
</pre>
</div> </dd> <dt><code>:result-string</code></dt> <dt><code>:eg-result-string</code></dt> <dd>
<p>These two are the same as <code>:result</code> and <code>:eg-result</code>, respectively, but are inserted as is. This is useful when the result is unreadable or should be of a particular form: </p> <div class="example"> <pre class="example">:no-eval (find-file "/tmp/foo")
:eg-result-string "#<buffer foo>"
:no-eval (default-file-modes)
:eg-result-string "#o755"
</pre>
</div> </dd> <dt><code>:no-manual</code></dt> <dd>
<p>Indicates that this function is not documented in the manual. </p> </dd> <dt><code>:args</code></dt> <dd>
<p>By default, the function’s actual argument list is shown. If <code>:args</code> is present, they are used instead. </p> <div class="example"> <pre class="example">:args (regexp string)
</pre>
</div> </dd> </dl> <p>Here’s a very short example: </p> <div class="lisp"> <pre class="lisp">(define-short-documentation-group string
"Creating Strings"
(substring
:eval (substring "foobar" 0 3)
:eval (substring "foobar" 3))
(concat
:eval (concat "foo" "bar" "zot")))
</pre>
</div> <p>The first argument is the name of the group to be defined, and then follows any number of function descriptions. </p> </dd>
</dl> <p>A function can belong to any number of documentation groups. </p> <p>In addition to function descriptions, the list can also have string elements, which are used to divide a documentation group into sections. </p> <dl> <dt id="shortdoc-add-function">Function: <strong>shortdoc-add-function</strong> <em>shortdoc-add-function group section elem</em>
</dt> <dd>
<p>Lisp packages can add functions to groups with this command. Each <var>elem</var> should be a function description, as described above. <var>group</var> is the function group, and <var>section</var> is what section in the function group to insert the function into. </p> <p>If <var>group</var> doesn’t exist, it will be created. If <var>section</var> doesn’t exist, it will be added to the end of the function group. </p>
</dd>
</dl><div class="_attribution">
<p class="_attribution-p">
Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
<a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Groups.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Groups.html</a>
</p>
</div>
|
