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