diff options
Diffstat (limited to 'devdocs/elisp/accessing-documentation.html')
| -rw-r--r-- | devdocs/elisp/accessing-documentation.html | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/devdocs/elisp/accessing-documentation.html b/devdocs/elisp/accessing-documentation.html new file mode 100644 index 00000000..50c07a6d --- /dev/null +++ b/devdocs/elisp/accessing-documentation.html @@ -0,0 +1,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> |