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
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
<h3 class="section">Access to Documentation Strings</h3> <dl> <dt id="documentation-property">Function: <strong>documentation-property</strong> <em>symbol property &optional verbatim</em>
</dt> <dd>
<p>This function returns the documentation string recorded in <var>symbol</var>’s property list under property <var>property</var>. It is most often used to look up the documentation strings of variables, for which <var>property</var> is <code>variable-documentation</code>. However, it can also be used to look up other kinds of documentation, such as for customization groups (but for function documentation, use the <code>documentation</code> function, below). </p> <p>If the property value refers to a documentation string stored in the <samp>DOC</samp> file or a byte-compiled file, this function looks up that string and returns it. </p> <p>If the property value isn’t <code>nil</code>, isn’t a string, and doesn’t refer to text in a file, then it is evaluated as a Lisp expression to obtain a string. </p> <p>Finally, this function passes the string through <code>substitute-command-keys</code> to substitute key bindings (see <a href="keys-in-documentation">Keys in Documentation</a>). It skips this step if <var>verbatim</var> is non-<code>nil</code>. </p> <div class="example"> <pre class="example">(documentation-property 'command-line-processed
'variable-documentation)
⇒ "Non-nil once command line has been processed"
</pre>
<pre class="example">(symbol-plist 'command-line-processed)
⇒ (variable-documentation 188902)
</pre>
<pre class="example">(documentation-property 'emacs 'group-documentation)
⇒ "Customization of the One True Editor."
</pre>
</div> </dd>
</dl> <dl> <dt id="documentation">Function: <strong>documentation</strong> <em>function &optional verbatim</em>
</dt> <dd>
<p>This function returns the documentation string of <var>function</var>. It handles macros, named keyboard macros, and special forms, as well as ordinary functions. </p> <p>If <var>function</var> is a symbol, this function first looks for the <code>function-documentation</code> property of that symbol; if that has a non-<code>nil</code> value, the documentation comes from that value (if the value is not a string, it is evaluated). </p> <p>If <var>function</var> is not a symbol, or if it has no <code>function-documentation</code> property, then <code>documentation</code> extracts the documentation string from the actual function definition, reading it from a file if called for. </p> <p>Finally, unless <var>verbatim</var> is non-<code>nil</code>, this function calls <code>substitute-command-keys</code>. The result is the documentation string to return. </p> <p>The <code>documentation</code> function signals a <code>void-function</code> error if <var>function</var> has no function definition. However, it is OK if the function definition has no documentation string. In that case, <code>documentation</code> returns <code>nil</code>. </p>
</dd>
</dl> <dl> <dt id="face-documentation">Function: <strong>face-documentation</strong> <em>face</em>
</dt> <dd><p>This function returns the documentation string of <var>face</var> as a face. </p></dd>
</dl> <p>Here is an example of using the two functions, <code>documentation</code> and <code>documentation-property</code>, to display the documentation strings for several symbols in a <samp>*Help*</samp> buffer. </p> <div class="example"> <pre class="example">(defun describe-symbols (pattern)
"Describe the Emacs Lisp symbols matching PATTERN.
All symbols that have PATTERN in their name are described
in the *Help* buffer."
(interactive "sDescribe symbols matching: ")
(let ((describe-func
(lambda (s)
</pre>
<pre class="example"> ;; <span class="roman">Print description of symbol.</span>
(if (fboundp s) ; <span class="roman">It is a function.</span>
(princ
(format "%s\t%s\n%s\n\n" s
(if (commandp s)
(let ((keys (where-is-internal s)))
(if keys
(concat
"Keys: "
(mapconcat 'key-description
keys " "))
"Keys: none"))
"Function")
</pre>
<pre class="example"> (or (documentation s)
"not documented"))))
(if (boundp s) ; <span class="roman">It is a variable.</span>
</pre>
<pre class="example"> (princ
(format "%s\t%s\n%s\n\n" s
(if (custom-variable-p s)
"Option " "Variable")
</pre>
<pre class="example"> (or (documentation-property
s 'variable-documentation)
"not documented"))))))
sym-list)
</pre>
<pre class="example"> ;; <span class="roman">Build a list of symbols that match pattern.</span>
(mapatoms (lambda (sym)
(if (string-match pattern (symbol-name sym))
(setq sym-list (cons sym sym-list)))))
</pre>
<pre class="example"> ;; <span class="roman">Display the data.</span>
(help-setup-xref (list 'describe-symbols pattern)
(called-interactively-p 'interactive))
(with-help-window (help-buffer)
(mapcar describe-func (sort sym-list 'string<)))))
</pre>
</div> <p>The <code>describe-symbols</code> function works like <code>apropos</code>, but provides more information. </p> <div class="example"> <pre class="example">(describe-symbols "goal")
---------- Buffer: *Help* ----------
goal-column Option
Semipermanent goal column for vertical motion, as set by …
</pre>
<pre class="example">minibuffer-temporary-goal-position Variable
not documented
</pre>
<pre class="example">set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
</pre>
<pre class="example">Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument ARG, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable ‘goal-column’.
(fn ARG)
</pre>
<pre class="example">temporary-goal-column Variable
Current goal column for vertical motion.
It is the column where point was at the start of the current run
of vertical motion commands.
When moving by visual lines via the function ‘line-move-visual’, it is a cons
cell (COL . HSCROLL), where COL is the x-position, in pixels,
divided by the default column width, and HSCROLL is the number of
columns by which window is scrolled from left margin.
When the ‘track-eol’ feature is doing its job, the value is
‘most-positive-fixnum’.
---------- Buffer: *Help* ----------
</pre>
</div> <dl> <dt id="Snarf-documentation">Function: <strong>Snarf-documentation</strong> <em>filename</em>
</dt> <dd>
<p>This function is used when building Emacs, just before the runnable Emacs is dumped. It finds the positions of the documentation strings stored in the file <var>filename</var>, and records those positions into memory in the function definitions and variable property lists. See <a href="building-emacs">Building Emacs</a>. </p> <p>Emacs reads the file <var>filename</var> from the <samp>emacs/etc</samp> directory. When the dumped Emacs is later executed, the same file will be looked for in the directory <code>doc-directory</code>. Usually <var>filename</var> is <code>"DOC"</code>. </p>
</dd>
</dl> <dl> <dt id="doc-directory">Variable: <strong>doc-directory</strong>
</dt> <dd>
<p>This variable holds the name of the directory which should contain the file <code>"DOC"</code> that contains documentation strings for built-in and preloaded functions and variables. </p> <p>In most cases, this is the same as <code>data-directory</code>. They may be different when you run Emacs from the directory where you built it, without actually installing it. See <a href="help-functions#Definition-of-data_002ddirectory">Definition of data-directory</a>. </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/Accessing-Documentation.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Accessing-Documentation.html</a>
</p>
</div>
|
