emacsPackages: update documentation

doc/packages/emacs.section.md

@@ -1,8 +1,15 @@
 # Emacs {#sec-emacs}
 
+Emacs is the advanced, extensible, customizable, self-documenting editor.
+
+At its core is an interpreter for Emacs Lisp (shortly, Elisp), a dialect of the Lisp programming language with extensions to support text editing.
+
 ## Configuring Emacs {#sec-emacs-config}
 
-The Emacs package comes with some extra helpers to make it easier to configure. `emacs.pkgs.withPackages` allows you to manage packages from ELPA. This means that you will not have to install that packages from within Emacs. For instance, if you wanted to use `company` `counsel`, `flycheck`, `ivy`, `magit`, `projectile`, and `use-package` you could use this as a `~/.config/nixpkgs/config.nix` override:
+Nixpkgs provides a framework that allows configuring Emacs easily via Nix.
+
+`emacs.pkgs.withPackages` allows managing packages from various Elisp package repositories (ELPA, MELPA etc.) and even third-party stand-alone packages from Nix, so that you will not have to install them from within Emacs.
+For instance, if you wanted to use `company` `counsel`, `flycheck`, `ivy`,`magit`, `projectile`, and `use-package` you could use this override in `~/.config/nixpkgs/config.nix`:
 
 ```nix
 {
@@ -20,7 +27,10 @@ The Emacs package comes with some extra helpers to make it easier to configure.
 }
 ```
 
-You can install it like any other packages via `nix-env -iA myEmacs`. However, this will only install those packages. It will not `configure` them for us. To do this, we need to provide a configuration file. Luckily, it is possible to do this from within Nix! By modifying the above example, we can make Emacs load a custom config file. The key is to create a package that provides a `default.el` file in `/share/emacs/site-start/`. Emacs knows to load this file automatically when it starts.
+You can install it like any other packages via `nix-env -iA myEmacs`.
+However, this will only install those packages. It will not _configure_ them.
+To do this, we need to provide a configuration file.
+Luckily, it is possible to do this from within Nix! By modifying the above example, we can make Emacs load a custom config file. The key is to create a package that provides a `default.el` file in `/share/emacs/site-start/`. Emacs knows to load this file automatically when it starts.
 
 ```nix
 {
@@ -116,3 +126,128 @@ in
   ])
 ```
 }
+
+## Elisp Packages {#sec-emacs-elisp-packages}
+
+Since at least version 24, Emacs has a native package manager, `package.el`.
+Since its inception, many Elisp packages were created by Emacs community at large, as well as Elisp package repositories.
+
+<!--
+Note: add a sun chapter about melpaBuild
+-->
+
+### Bulk Update {#sec-emacs-elisp-packages-bulk-update}
+
+The chief Elisp package repositories are [GNU ELPA](https://elpa.gnu.org/), [NonGNU ELPA](https://elpa.nongnu.org/), and [MELPA](https://melpa.org/).
+
+Nixpkgs provides a comprehensive infrastucture that leverages the contents of these Elisp repositories as Nix packages. This chapter  describes the bulk-updating automation tooling.
+
+Inside the `emacs` directory lives the `elisp-packages` subdirectory.
+Inside it we provide the following scripts:
+
+- `update-scripts_library.sh`
+
+  This file serves as a library, containing useful functions to deal with bulk updates.
+  It can be `source`'d in both interactive and batch environments.
+
+  This library provides the following functions:
+
+  - `download_packageset`
+
+    This function downloads from [`nix-community` Emacs Overlay](https://github.com/nix-community/emacs-overlay) the corresponding files.
+
+    It accepts one argument.
+    This argument can assume one of the following values:
+    `elpa`, `elpa-devel`,  `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`.
+
+  - `test_packageset`
+
+    This function runs a simple test that instantiates the corresponding package set.
+
+    It accepts one argument.
+    This argument can assume one of the following values:
+    `elpa`, `elpa-devel`,  `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`.
+
+  - `commit_packageset`
+
+    This function commits the corresponding package set to the Nixpkgs repository, writing a one-line descriptive commit message.
+
+    It accepts two arguments.
+
+    The first argument can assume one of the following values: `elpa`,
+    `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`.
+    The second argument is an optional free-form string used verbatim, describing the origin of the change being committed.
+    Its default value is `interactive session`.
+
+- `update-package-sets`
+
+  This script updates the package sets passed to it as arguments.
+
+  It accepts multiple arguments.
+  Each argument can assume one of the following values:
+  `elpa`, `elpa-devel`, `nongnu`, `nongnu-devel`.
+
+- `update-melpa`
+
+  This script updates `recipes-archive-melpa.json`, a JSON file that describes the MELPA package set.
+
+  It accepts no arguments.
+
+- `update-from-overlay`
+
+  This script downloads all the packagesets from overlay, then tests and commits them.
+
+  It accepts no arguments.
+- `update-scripts_library.sh`
+
+  This file serves as a library, containing useful functions to deal with bulk updates.
+  It can be `source`'d in both interactive and batch environments.
+
+  This library provides the following functions:
+
+  - `download_packageset`
+
+    This function downloads from [`nix-community` Emacs Overlay](https://github.com/nix-community/emacs-overlay) the corresponding files.
+
+    It accepts one argument.
+    This argument can assume one of the following values:
+    `elpa`, `elpa-devel`,  `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`.
+
+  - `test_packageset`
+
+    This function runs a simple test that instantiates the corresponding package set.
+
+    It accepts one argument.
+    This argument can assume one of the following values:
+    `elpa`, `elpa-devel`,  `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`.
+
+  - `commit_packageset`
+
+    This function commits the corresponding package set to the Nixpkgs repository, writing a one-line descriptive commit message.
+
+    It accepts two arguments.
+
+    The first argument can assume one of the following values: `elpa`,
+    `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`.
+    The second argument is an optional free-form string used verbatim, describing the origin of the change being committed.
+    Its default value is `interactive session`.
+
+- `update-package-sets`
+
+  This script updates the package sets passed to it as arguments.
+
+  It accepts multiple arguments.
+  Each argument can assume one of the following values:
+  `elpa`, `elpa-devel`, `nongnu`, `nongnu-devel`.
+
+- `update-melpa`
+
+  This script updates `recipes-archive-melpa.json`, a JSON file that describes the MELPA package set.
+
+  It accepts no arguments.
+
+- `update-from-overlay`
+
+  This script downloads all the packagesets from overlay, then tests and commits them.
+
+  It accepts no arguments.