diff options
Diffstat (limited to 'devdocs/elisp/documentation-groups.html')
| -rw-r--r-- | devdocs/elisp/documentation-groups.html | 63 |
1 files changed, 63 insertions, 0 deletions
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 @@ + <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> |