new repository

1 files changed, 32 insertions, 0 deletions

diff --git a/devdocs/elisp/tips-for-defining.html b/devdocs/elisp/tips-for-defining.html
new file mode 100644
index 00000000..fa6ef45a
--- /dev/null
+++ b/devdocs/elisp/tips-for-defining.html
@@ -0,0 +1,32 @@
+ <h3 class="section">Tips for Defining Variables Robustly</h3> <p>When you define a variable whose value is a function, or a list of functions, use a name that ends in ‘<samp>-function</samp>’ or ‘<samp>-functions</samp>’, respectively. </p> <p>There are several other variable name conventions; here is a complete list: </p> <dl compact> <dt>‘<samp>…-hook</samp>’</dt> <dd>
+<p>The variable is a normal hook (see <a href="hooks">Hooks</a>). </p> </dd> <dt>‘<samp>…-function</samp>’</dt> <dd>
+<p>The value is a function. </p> </dd> <dt>‘<samp>…-functions</samp>’</dt> <dd>
+<p>The value is a list of functions. </p> </dd> <dt>‘<samp>…-form</samp>’</dt> <dd>
+<p>The value is a form (an expression). </p> </dd> <dt>‘<samp>…-forms</samp>’</dt> <dd>
+<p>The value is a list of forms (expressions). </p> </dd> <dt>‘<samp>…-predicate</samp>’</dt> <dd>
+<p>The value is a predicate—a function of one argument that returns non-<code>nil</code> for success and <code>nil</code> for failure. </p> </dd> <dt>‘<samp>…-flag</samp>’</dt> <dd>
+<p>The value is significant only as to whether it is <code>nil</code> or not. Since such variables often end up acquiring more values over time, this convention is not strongly recommended. </p> </dd> <dt>‘<samp>…-program</samp>’</dt> <dd>
+<p>The value is a program name. </p> </dd> <dt>‘<samp>…-command</samp>’</dt> <dd>
+<p>The value is a whole shell command. </p> </dd> <dt>‘<samp>…-switches</samp>’</dt> <dd>
+<p>The value specifies options for a command. </p> </dd> <dt>‘<samp><var>prefix</var>--…</samp>’</dt> <dd>
+<p>The variable is intended for internal use and is defined in the file <samp><var>prefix</var>.el</samp>. (Emacs code contributed before 2018 may follow other conventions, which are being phased out.) </p> </dd> <dt>‘<samp>…-internal</samp>’</dt> <dd><p>The variable is intended for internal use and is defined in C code. (Emacs code contributed before 2018 may follow other conventions, which are being phased out.) </p></dd> </dl> <p>When you define a variable, always consider whether you should mark it as safe or risky; see <a href="file-local-variables">File Local Variables</a>. </p> <p>When defining and initializing a variable that holds a complicated value (such as a keymap with bindings in it), it’s best to put the entire computation of the value into the <code>defvar</code>, like this: </p> <div class="example"> <pre class="example">(defvar my-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map "\C-c\C-a" 'my-command)
+    …
+    map)
+  <var>docstring</var>)
+</pre>
+</div> <p>This method has several benefits. First, if the user quits while loading the file, the variable is either still uninitialized or initialized properly, never in-between. If it is still uninitialized, reloading the file will initialize it properly. Second, reloading the file once the variable is initialized will not alter it; that is important if the user has run hooks to alter part of the contents (such as, to rebind keys). Third, evaluating the <code>defvar</code> form with <kbd>C-M-x</kbd> will reinitialize the map completely. </p> <p>Putting so much code in the <code>defvar</code> form has one disadvantage: it puts the documentation string far away from the line which names the variable. Here’s a safe way to avoid that: </p> <div class="example"> <pre class="example">(defvar my-mode-map nil
+  <var>docstring</var>)
+(unless my-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map "\C-c\C-a" 'my-command)
+    …
+    (setq my-mode-map map)))
+</pre>
+</div> <p>This has all the same advantages as putting the initialization inside the <code>defvar</code>, except that you must type <kbd>C-M-x</kbd> twice, once on each form, if you do want to reinitialize the variable. </p><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/Tips-for-Defining.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips-for-Defining.html</a>
+  </p>
+</div>