new repository

1 files changed, 16 insertions, 0 deletions

diff --git a/devdocs/elisp/user_002dchosen-coding-systems.html b/devdocs/elisp/user_002dchosen-coding-systems.html
new file mode 100644
index 00000000..d58ce76b
--- /dev/null
+++ b/devdocs/elisp/user_002dchosen-coding-systems.html
@@ -0,0 +1,16 @@
+ <h4 class="subsection">User-Chosen Coding Systems</h4>  <dl> <dt id="select-safe-coding-system">Function: <strong>select-safe-coding-system</strong> <em>from to &amp;optional default-coding-system accept-default-p file</em>
+</dt> <dd>
+<p>This function selects a coding system for encoding specified text, asking the user to choose if necessary. Normally the specified text is the text in the current buffer between <var>from</var> and <var>to</var>. If <var>from</var> is a string, the string specifies the text to encode, and <var>to</var> is ignored. </p> <p>If the specified text includes raw bytes (see <a href="text-representations">Text Representations</a>), <code>select-safe-coding-system</code> suggests <code>raw-text</code> for its encoding. </p> <p>If <var>default-coding-system</var> is non-<code>nil</code>, that is the first coding system to try; if that can handle the text, <code>select-safe-coding-system</code> returns that coding system. It can also be a list of coding systems; then the function tries each of them one by one. After trying all of them, it next tries the current buffer’s value of <code>buffer-file-coding-system</code> (if it is not <code>undecided</code>), then the default value of <code>buffer-file-coding-system</code> and finally the user’s most preferred coding system, which the user can set using the command <code>prefer-coding-system</code> (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Recognize-Coding.html#Recognize-Coding">Recognizing Coding Systems</a> in <cite>The GNU Emacs Manual</cite>). </p> <p>If one of those coding systems can safely encode all the specified text, <code>select-safe-coding-system</code> chooses it and returns it. Otherwise, it asks the user to choose from a list of coding systems which can encode all the text, and returns the user’s choice. </p> <p><var>default-coding-system</var> can also be a list whose first element is <code>t</code> and whose other elements are coding systems. Then, if no coding system in the list can handle the text, <code>select-safe-coding-system</code> queries the user immediately, without trying any of the three alternatives described above. This is handy for checking only the coding systems in the list. </p> <p>The optional argument <var>accept-default-p</var> determines whether a coding system selected without user interaction is acceptable. If it’s omitted or <code>nil</code>, such a silent selection is always acceptable. If it is non-<code>nil</code>, it should be a function; <code>select-safe-coding-system</code> calls this function with one argument, the base coding system of the selected coding system. If the function returns <code>nil</code>, <code>select-safe-coding-system</code> rejects the silently selected coding system, and asks the user to select a coding system from a list of possible candidates. </p>  <p>If the variable <code>select-safe-coding-system-accept-default-p</code> is non-<code>nil</code>, it should be a function taking a single argument. It is used in place of <var>accept-default-p</var>, overriding any value supplied for this argument. </p> <p>As a final step, before returning the chosen coding system, <code>select-safe-coding-system</code> checks whether that coding system is consistent with what would be selected if the contents of the region were read from a file. (If not, this could lead to data corruption in a file subsequently re-visited and edited.) Normally, <code>select-safe-coding-system</code> uses <code>buffer-file-name</code> as the file for this purpose, but if <var>file</var> is non-<code>nil</code>, it uses that file instead (this can be relevant for <code>write-region</code> and similar functions). If it detects an apparent inconsistency, <code>select-safe-coding-system</code> queries the user before selecting the coding system. </p>
+</dd>
+</dl> <dl> <dt id="select-safe-coding-system-function">Variable: <strong>select-safe-coding-system-function</strong>
+</dt> <dd><p>This variable names the function to be called to request the user to select a proper coding system for encoding text when the default coding system for an output operation cannot safely encode that text. The default value of this variable is <code>select-safe-coding-system</code>. Emacs primitives that write text to files, such as <code>write-region</code>, or send text to other processes, such as <code>process-send-region</code>, normally call the value of this variable, unless <code>coding-system-for-write</code> is bound to a non-<code>nil</code> value (see <a href="specifying-coding-systems">Specifying Coding Systems</a>). </p></dd>
+</dl> <p>Here are two functions you can use to let the user specify a coding system, with completion. See <a href="completion">Completion</a>. </p> <dl> <dt id="read-coding-system">Function: <strong>read-coding-system</strong> <em>prompt &amp;optional default</em>
+</dt> <dd><p>This function reads a coding system using the minibuffer, prompting with string <var>prompt</var>, and returns the coding system name as a symbol. If the user enters null input, <var>default</var> specifies which coding system to return. It should be a symbol or a string. </p></dd>
+</dl> <dl> <dt id="read-non-nil-coding-system">Function: <strong>read-non-nil-coding-system</strong> <em>prompt</em>
+</dt> <dd><p>This function reads a coding system using the minibuffer, prompting with string <var>prompt</var>, and returns the coding system name as a symbol. If the user tries to enter null input, it asks the user to try again. See <a href="coding-systems">Coding Systems</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/User_002dChosen-Coding-Systems.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/User_002dChosen-Coding-Systems.html</a>
+  </p>
+</div>