new repository

1 files changed, 42 insertions, 0 deletions

diff --git a/devdocs/elisp/visiting-functions.html b/devdocs/elisp/visiting-functions.html
new file mode 100644
index 00000000..cdad5765
--- /dev/null
+++ b/devdocs/elisp/visiting-functions.html
@@ -0,0 +1,42 @@
+ <h4 class="subsection">Functions for Visiting Files</h4>   <p>This section describes the functions normally used to visit files. For historical reasons, these functions have names starting with ‘<samp>find-</samp>’ rather than ‘<samp>visit-</samp>’. See <a href="buffer-file-name">Buffer File Name</a>, for functions and variables that access the visited file name of a buffer or that find an existing buffer by its visited file name. </p> <p>In a Lisp program, if you want to look at the contents of a file but not alter it, the fastest way is to use <code>insert-file-contents</code> in a temporary buffer. Visiting the file is not necessary and takes longer. See <a href="reading-from-files">Reading from Files</a>. </p> <dl> <dt id="find-file">Command: <strong>find-file</strong> <em>filename &amp;optional wildcards</em>
+</dt> <dd>
+<p>This command selects a buffer visiting the file <var>filename</var>, using an existing buffer if there is one, and otherwise creating a new buffer and reading the file into it. It also returns that buffer. </p> <p>Aside from some technical details, the body of the <code>find-file</code> function is basically equivalent to: </p> <div class="example"> <pre class="example">(switch-to-buffer (find-file-noselect filename nil nil wildcards))
+</pre>
+</div> <p>(See <code>switch-to-buffer</code> in <a href="switching-buffers">Switching Buffers</a>.) </p> <p>If <var>wildcards</var> is non-<code>nil</code>, which is always true in an interactive call, then <code>find-file</code> expands wildcard characters in <var>filename</var> and visits all the matching files. </p> <p>When <code>find-file</code> is called interactively, it prompts for <var>filename</var> in the minibuffer. </p>
+</dd>
+</dl> <dl> <dt id="find-file-literally">Command: <strong>find-file-literally</strong> <em>filename</em>
+</dt> <dd>
+<p>This command visits <var>filename</var>, like <code>find-file</code> does, but it does not perform any format conversions (see <a href="format-conversion">Format Conversion</a>), character code conversions (see <a href="coding-systems">Coding Systems</a>), or end-of-line conversions (see <a href="coding-system-basics">End of line conversion</a>). The buffer visiting the file is made unibyte, and its major mode is Fundamental mode, regardless of the file name. File local variable specifications in the file (see <a href="file-local-variables">File Local Variables</a>) are ignored, and automatic decompression and adding a newline at the end of the file due to <code>require-final-newline</code> (see <a href="saving-buffers">require-final-newline</a>) are also disabled. </p> <p>Note that if Emacs already has a buffer visiting the same file non-literally, it will not visit the same file literally, but instead just switch to the existing buffer. If you want to be sure of accessing a file’s contents literally, you should create a temporary buffer and then read the file contents into it using <code>insert-file-contents-literally</code> (see <a href="reading-from-files">Reading from Files</a>). </p>
+</dd>
+</dl> <dl> <dt id="find-file-noselect">Function: <strong>find-file-noselect</strong> <em>filename &amp;optional nowarn rawfile wildcards</em>
+</dt> <dd>
+<p>This function is the guts of all the file-visiting functions. It returns a buffer visiting the file <var>filename</var>. You may make the buffer current or display it in a window if you wish, but this function does not do so. </p> <p>The function returns an existing buffer if there is one; otherwise it creates a new buffer and reads the file into it. When <code>find-file-noselect</code> uses an existing buffer, it first verifies that the file has not changed since it was last visited or saved in that buffer. If the file has changed, this function asks the user whether to reread the changed file. If the user says ‘<samp>yes</samp>’, any edits previously made in the buffer are lost. </p> <p>Reading the file involves decoding the file’s contents (see <a href="coding-systems">Coding Systems</a>), including end-of-line conversion, and format conversion (see <a href="format-conversion">Format Conversion</a>). If <var>wildcards</var> is non-<code>nil</code>, then <code>find-file-noselect</code> expands wildcard characters in <var>filename</var> and visits all the matching files. </p> <p>This function displays warning or advisory messages in various peculiar cases, unless the optional argument <var>nowarn</var> is non-<code>nil</code>. For example, if it needs to create a buffer, and there is no file named <var>filename</var>, it displays the message ‘<samp>(New file)</samp>’ in the echo area, and leaves the buffer empty. </p> <p>The <code>find-file-noselect</code> function normally calls <code>after-find-file</code> after reading the file (see <a href="subroutines-of-visiting">Subroutines of Visiting</a>). That function sets the buffer major mode, parses local variables, warns the user if there exists an auto-save file more recent than the file just visited, and finishes by running the functions in <code>find-file-hook</code>. </p> <p>If the optional argument <var>rawfile</var> is non-<code>nil</code>, then <code>after-find-file</code> is not called, and the <code>find-file-not-found-functions</code> are not run in case of failure. What’s more, a non-<code>nil</code> <var>rawfile</var> value suppresses coding system conversion and format conversion. </p> <p>The <code>find-file-noselect</code> function usually returns the buffer that is visiting the file <var>filename</var>. But, if wildcards are actually used and expanded, it returns a list of buffers that are visiting the various files. </p> <div class="example"> <pre class="example">(find-file-noselect "/etc/fstab")
+     ⇒ #&lt;buffer fstab&gt;
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="find-file-other-window">Command: <strong>find-file-other-window</strong> <em>filename &amp;optional wildcards</em>
+</dt> <dd>
+<p>This command selects a buffer visiting the file <var>filename</var>, but does so in a window other than the selected window. It may use another existing window or split a window; see <a href="switching-buffers">Switching Buffers</a>. </p> <p>When this command is called interactively, it prompts for <var>filename</var>. </p>
+</dd>
+</dl> <dl> <dt id="find-file-read-only">Command: <strong>find-file-read-only</strong> <em>filename &amp;optional wildcards</em>
+</dt> <dd>
+<p>This command selects a buffer visiting the file <var>filename</var>, like <code>find-file</code>, but it marks the buffer as read-only. See <a href="read-only-buffers">Read Only Buffers</a>, for related functions and variables. </p> <p>When this command is called interactively, it prompts for <var>filename</var>. </p>
+</dd>
+</dl> <dl> <dt id="find-file-wildcards">User Option: <strong>find-file-wildcards</strong>
+</dt> <dd><p>If this variable is non-<code>nil</code>, then the various <code>find-file</code> commands check for wildcard characters and visit all the files that match them (when invoked interactively or when their <var>wildcards</var> argument is non-<code>nil</code>). If this option is <code>nil</code>, then the <code>find-file</code> commands ignore their <var>wildcards</var> argument and never treat wildcard characters specially. </p></dd>
+</dl> <dl> <dt id="find-file-hook">User Option: <strong>find-file-hook</strong>
+</dt> <dd>
+<p>The value of this variable is a list of functions to be called after a file is visited. The file’s local-variables specification (if any) will have been processed before the hooks are run. The buffer visiting the file is current when the hook functions are run. </p> <p>This variable is a normal hook. See <a href="hooks">Hooks</a>. </p>
+</dd>
+</dl> <dl> <dt id="find-file-not-found-functions">Variable: <strong>find-file-not-found-functions</strong>
+</dt> <dd>
+<p>The value of this variable is a list of functions to be called when <code>find-file</code> or <code>find-file-noselect</code> is passed a nonexistent file name. <code>find-file-noselect</code> calls these functions as soon as it detects a nonexistent file. It calls them in the order of the list, until one of them returns non-<code>nil</code>. <code>buffer-file-name</code> is already set up. </p> <p>This is not a normal hook because the values of the functions are used, and in many cases only some of the functions are called. </p>
+</dd>
+</dl> <dl> <dt id="find-file-literally">Variable: <strong>find-file-literally</strong>
+</dt> <dd><p>This buffer-local variable, if set to a non-<code>nil</code> value, makes <code>save-buffer</code> behave as if the buffer were visiting its file literally, i.e., without conversions of any kind. The command <code>find-file-literally</code> sets this variable’s local value, but other equivalent functions and commands can do that as well, e.g., to avoid automatic addition of a newline at the end of the file. This variable is permanent local, so it is unaffected by changes of major modes. </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/Visiting-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Visiting-Functions.html</a>
+  </p>
+</div>