new repository

1 files changed, 40 insertions, 0 deletions

diff --git a/devdocs/elisp/named-features.html b/devdocs/elisp/named-features.html
new file mode 100644
index 00000000..0bf51d43
--- /dev/null
+++ b/devdocs/elisp/named-features.html
@@ -0,0 +1,40 @@
+ <h3 class="section">Features</h3>    <p><code>provide</code> and <code>require</code> are an alternative to <code>autoload</code> for loading files automatically. They work in terms of named <em>features</em>. Autoloading is triggered by calling a specific function, but a feature is loaded the first time another program asks for it by name. </p> <p>A feature name is a symbol that stands for a collection of functions, variables, etc. The file that defines them should <em>provide</em> the feature. Another program that uses them may ensure they are defined by <em>requiring</em> the feature. This loads the file of definitions if it hasn’t been loaded already. </p>  <p>To require the presence of a feature, call <code>require</code> with the feature name as argument. <code>require</code> looks in the global variable <code>features</code> to see whether the desired feature has been provided already. If not, it loads the feature from the appropriate file. This file should call <code>provide</code> at the top level to add the feature to <code>features</code>; if it fails to do so, <code>require</code> signals an error. </p> <p>For example, in <samp>idlwave.el</samp>, the definition for <code>idlwave-complete-filename</code> includes the following code: </p> <div class="example"> <pre class="example">(defun idlwave-complete-filename ()
+  "Use the comint stuff to complete a file name."
+   (require 'comint)
+   (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%={}\\-")
+          (comint-completion-addsuffix nil)
+          ...)
+       (comint-dynamic-complete-filename)))
+</pre>
+</div> <p>The expression <code>(require 'comint)</code> loads the file <samp>comint.el</samp> if it has not yet been loaded, ensuring that <code>comint-dynamic-complete-filename</code> is defined. Features are normally named after the files that provide them, so that <code>require</code> need not be given the file name. (Note that it is important that the <code>require</code> statement be outside the body of the <code>let</code>. Loading a library while its variables are let-bound can have unintended consequences, namely the variables becoming unbound after the let exits.) </p> <p>The <samp>comint.el</samp> file contains the following top-level expression: </p> <div class="example"> <pre class="example">(provide 'comint)
+</pre>
+</div> <p>This adds <code>comint</code> to the global <code>features</code> list, so that <code>(require 'comint)</code> will henceforth know that nothing needs to be done. </p>  <p>When <code>require</code> is used at top level in a file, it takes effect when you byte-compile that file (see <a href="byte-compilation">Byte Compilation</a>) as well as when you load it. This is in case the required package contains macros that the byte compiler must know about. It also avoids byte compiler warnings for functions and variables defined in the file loaded with <code>require</code>. </p> <p>Although top-level calls to <code>require</code> are evaluated during byte compilation, <code>provide</code> calls are not. Therefore, you can ensure that a file of definitions is loaded before it is byte-compiled by including a <code>provide</code> followed by a <code>require</code> for the same feature, as in the following example. </p> <div class="example"> <pre class="example">(provide 'my-feature)  ; <span class="roman">Ignored by byte compiler,</span>
+                       ;   <span class="roman">evaluated by <code>load</code>.</span>
+(require 'my-feature)  ; <span class="roman">Evaluated by byte compiler.</span>
+</pre>
+</div> <p>The compiler ignores the <code>provide</code>, then processes the <code>require</code> by loading the file in question. Loading the file does execute the <code>provide</code> call, so the subsequent <code>require</code> call does nothing when the file is loaded. </p> <dl> <dt id="provide">Function: <strong>provide</strong> <em>feature &amp;optional subfeatures</em>
+</dt> <dd>
+<p>This function announces that <var>feature</var> is now loaded, or being loaded, into the current Emacs session. This means that the facilities associated with <var>feature</var> are or will be available for other Lisp programs. </p> <p>The direct effect of calling <code>provide</code> is to add <var>feature</var> to the front of <code>features</code> if it is not already in that list and call any <code>eval-after-load</code> code waiting for it (see <a href="hooks-for-loading">Hooks for Loading</a>). The argument <var>feature</var> must be a symbol. <code>provide</code> returns <var>feature</var>. </p> <p>If provided, <var>subfeatures</var> should be a list of symbols indicating a set of specific subfeatures provided by this version of <var>feature</var>. You can test the presence of a subfeature using <code>featurep</code>. The idea of subfeatures is that you use them when a package (which is one <var>feature</var>) is complex enough to make it useful to give names to various parts or functionalities of the package, which might or might not be loaded, or might or might not be present in a given version. See <a href="network-feature-testing">Network Feature Testing</a>, for an example. </p> <div class="example"> <pre class="example">features
+     ⇒ (bar bish)
+
+(provide 'foo)
+     ⇒ foo
+features
+     ⇒ (foo bar bish)
+</pre>
+</div> <p>When a file is loaded to satisfy an autoload, and it stops due to an error in the evaluation of its contents, any function definitions or <code>provide</code> calls that occurred during the load are undone. See <a href="autoload">Autoload</a>. </p>
+</dd>
+</dl> <dl> <dt id="require">Function: <strong>require</strong> <em>feature &amp;optional filename noerror</em>
+</dt> <dd>
+<p>This function checks whether <var>feature</var> is present in the current Emacs session (using <code>(featurep <var>feature</var>)</code>; see below). The argument <var>feature</var> must be a symbol. </p> <p>If the feature is not present, then <code>require</code> loads <var>filename</var> with <code>load</code>. If <var>filename</var> is not supplied, then the name of the symbol <var>feature</var> is used as the base file name to load. However, in this case, <code>require</code> insists on finding <var>feature</var> with an added ‘<samp>.el</samp>’ or ‘<samp>.elc</samp>’ suffix (possibly extended with a compression suffix); a file whose name is just <var>feature</var> won’t be used. (The variable <code>load-suffixes</code> specifies the exact required Lisp suffixes.) </p> <p>If <var>noerror</var> is non-<code>nil</code>, that suppresses errors from actual loading of the file. In that case, <code>require</code> returns <code>nil</code> if loading the file fails. Normally, <code>require</code> returns <var>feature</var>. </p> <p>If loading the file succeeds but does not provide <var>feature</var>, <code>require</code> signals an error about the missing feature. </p>
+</dd>
+</dl> <dl> <dt id="featurep">Function: <strong>featurep</strong> <em>feature &amp;optional subfeature</em>
+</dt> <dd><p>This function returns <code>t</code> if <var>feature</var> has been provided in the current Emacs session (i.e., if <var>feature</var> is a member of <code>features</code>.) If <var>subfeature</var> is non-<code>nil</code>, then the function returns <code>t</code> only if that subfeature is provided as well (i.e., if <var>subfeature</var> is a member of the <code>subfeature</code> property of the <var>feature</var> symbol.) </p></dd>
+</dl> <dl> <dt id="features">Variable: <strong>features</strong>
+</dt> <dd><p>The value of this variable is a list of symbols that are the features loaded in the current Emacs session. Each symbol was put in this list with a call to <code>provide</code>. The order of the elements in the <code>features</code> list is not significant. </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/Named-Features.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Named-Features.html</a>
+  </p>
+</div>