new repository

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 &amp;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 &amp;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&lt;)))))
+</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 &copy; 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>