new repository

1 files changed, 18 insertions, 0 deletions

diff --git a/devdocs/elisp/packaging-basics.html b/devdocs/elisp/packaging-basics.html
new file mode 100644
index 00000000..d472a4ee
--- /dev/null
+++ b/devdocs/elisp/packaging-basics.html
@@ -0,0 +1,18 @@
+ <h3 class="section">Packaging Basics</h3>      <p>A package is either a <em>simple package</em> or a <em>multi-file package</em>. A simple package is stored in a package archive as a single Emacs Lisp file, while a multi-file package is stored as a tar file (containing multiple Lisp files, and possibly non-Lisp files such as a manual). </p> <p>In ordinary usage, the difference between simple packages and multi-file packages is relatively unimportant; the Package Menu interface makes no distinction between them. However, the procedure for creating them differs, as explained in the following sections. </p> <p>Each package (whether simple or multi-file) has certain <em>attributes</em>: </p> <dl compact> <dt>Name</dt> <dd>
+<p>A short word (e.g., ‘<samp>auctex</samp>’). This is usually also the symbol prefix used in the program (see <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Coding-Conventions.html">Coding Conventions</a>). </p> </dd> <dt>Version</dt> <dd>
+<p>A version number, in a form that the function <code>version-to-list</code> understands (e.g., ‘<samp>11.86</samp>’). Each release of a package should be accompanied by an increase in the version number so that it will be recognized as an upgrade by users querying the package archive. </p> </dd> <dt>Brief description</dt> <dd>
+<p>This is shown when the package is listed in the Package Menu. It should occupy a single line, ideally in 36 characters or less. </p> </dd> <dt>Long description</dt> <dd>
+<p>This is shown in the buffer created by <kbd>C-h P</kbd> (<code>describe-package</code>), following the package’s brief description and installation status. It normally spans multiple lines, and should fully describe the package’s capabilities and how to begin using it once it is installed. </p> </dd> <dt>Dependencies</dt> <dd><p>A list of other packages (possibly including minimal acceptable version numbers) on which this package depends. The list may be empty, meaning this package has no dependencies. Otherwise, installing this package also automatically installs its dependencies, recursively; if any dependency cannot be found, the package cannot be installed. </p></dd> </dl>  <p>Installing a package, either via the command <code>package-install-file</code>, or via the Package Menu, creates a subdirectory of <code>package-user-dir</code> named <samp><var>name</var>-<var>version</var></samp>, where <var>name</var> is the package’s name and <var>version</var> its version (e.g., <samp>~/.emacs.d/elpa/auctex-11.86/</samp>). We call this the package’s <em>content directory</em>. It is where Emacs puts the package’s contents (the single Lisp file for a simple package, or the files extracted from a multi-file package). </p>  <p>Emacs then searches every Lisp file in the content directory for autoload magic comments (see <a href="autoload">Autoload</a>). These autoload definitions are saved to a file named <samp><var>name</var>-autoloads.el</samp> in the content directory. They are typically used to autoload the principal user commands defined in the package, but they can also perform other tasks, such as adding an element to <code>auto-mode-alist</code> (see <a href="auto-major-mode">Auto Major Mode</a>). Note that a package typically does <em>not</em> autoload every function and variable defined within it—only the handful of commands typically called to begin using the package. Emacs then byte-compiles every Lisp file in the package. </p> <p>After installation, the installed package is <em>loaded</em>: Emacs adds the package’s content directory to <code>load-path</code>, and evaluates the autoload definitions in <samp><var>name</var>-autoloads.el</samp>. </p> <p>Whenever Emacs starts up, it automatically calls the function <code>package-activate-all</code> to make installed packages available to the current session. This is done after loading the early init file, but before loading the regular init file (see <a href="startup-summary">Startup Summary</a>). Packages are not automatically made available if the user option <code>package-enable-at-startup</code> is set to <code>nil</code> in the early init file. </p> <dl> <dt id="package-activate-all">Function: <strong>package-activate-all</strong>
+</dt> <dd>
+<p>This function makes the packages available to the current session. The user option <code>package-load-list</code> specifies which packages to make available; by default, all installed packages are made available. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Installation.html#Package-Installation">Package Installation</a> in <cite>The GNU Emacs Manual</cite>. </p> <p>In most cases, you should not need to call <code>package-activate-all</code>, as this is done automatically during startup. Simply make sure to put any code that should run before <code>package-activate-all</code> in the early init file, and any code that should run after it in the primary init file (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html#Init-File">Init File</a> in <cite>The GNU Emacs Manual</cite>). </p>
+</dd>
+</dl> <dl> <dt id="package-initialize">Command: <strong>package-initialize</strong> <em>&amp;optional no-activate</em>
+</dt> <dd>
+<p>This function initializes Emacs’ internal record of which packages are installed, and then calls <code>package-activate-all</code>. </p> <p>The optional argument <var>no-activate</var>, if non-<code>nil</code>, causes Emacs to update its record of installed packages without actually making them available. </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/Packaging-Basics.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Packaging-Basics.html</a>
+  </p>
+</div>