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.

pkgs/applications/editors/emacs/elisp-packages/elpa-devel-packages.nix

@@ -1,27 +1,3 @@
-/*
-
-# Updating
-
-To update the list of packages from ELPA,
-
-1. Run `./update-elpa-devel`.
-2. Check for evaluation errors:
-     # "../../../../../" points to the default.nix from root of Nixpkgs tree
-     env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../../ -A emacs.pkgs.elpaDevelPackages
-3. Run `git commit -m "elpa-devel-packages $(date -Idate)" -- elpa-devel-generated.nix`
-
-## Update from overlay
-
-Alternatively, run the following command:
-
-./update-from-overlay
-
-It will update both melpa and elpa packages using
-https://github.com/nix-community/emacs-overlay. It's almost instantenous and
-formats commits for you.
-
-*/
-
 { lib, pkgs, buildPackages }:
 
 self: let

pkgs/applications/editors/emacs/elisp-packages/elpa-packages.nix

@@ -1,27 +1,3 @@
-/*
-
-# Updating
-
-To update the list of packages from ELPA,
-
-1. Run `./update-elpa`.
-2. Check for evaluation errors:
-     # "../../../../../" points to the default.nix from root of Nixpkgs tree
-     env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../../ -A emacs.pkgs.elpaPackages
-3. Run `git commit -m "elpa-packages $(date -Idate)" -- elpa-generated.nix`
-
-## Update from overlay
-
-Alternatively, run the following command:
-
-./update-from-overlay
-
-It will update both melpa and elpa packages using
-https://github.com/nix-community/emacs-overlay. It's almost instantenous and
-formats commits for you.
-
-*/
-
 { lib, pkgs, buildPackages }:
 
 self: let

pkgs/applications/editors/emacs/elisp-packages/melpa-packages.nix

@@ -1,28 +1,3 @@
-/*
-
-# Updating
-
-To update the list of packages from MELPA,
-
-1. Run `./update-melpa`
-2. Check for evaluation errors:
-     # "../../../../../" points to the default.nix from root of Nixpkgs tree
-     env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate --show-trace ../../../../../ -A emacs.pkgs.melpaStablePackages
-     env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate --show-trace ../../../../../ -A emacs.pkgs.melpaPackages
-3. Run `git commit -m "melpa-packages $(date -Idate)" recipes-archive-melpa.json`
-
-## Update from overlay
-
-Alternatively, run the following command:
-
-./update-from-overlay
-
-It will update both melpa and elpa packages using
-https://github.com/nix-community/emacs-overlay. It's almost instantenous and
-formats commits for you.
-
-*/
-
 let
   # Read ./recipes-archive-melpa.json in an outer let to make sure we only do this once.
   defaultArchive = builtins.fromJSON (builtins.readFile ./recipes-archive-melpa.json);

pkgs/applications/editors/emacs/elisp-packages/nongnu-devel-packages.nix

@@ -1,15 +1,3 @@
-/*
-  # Updating
-
-  To update the list of packages from nongnu devel (ELPA),
-
-  1. Run `./update-nongnu-devel`.
-  2. Check for evaluation errors:
-       # "../../../../../" points to the default.nix from root of Nixpkgs tree
-       env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../../ -A emacs.pkgs.nongnuDevelPackages
-  3. Run `git commit -m "nongnu-devel-packages $(date -Idate)" -- nongnu-devel-generated.nix`
-*/
-
 {
   lib,
   pkgs,

pkgs/applications/editors/emacs/elisp-packages/nongnu-packages.nix

@@ -1,17 +1,3 @@
-/*
-
-# Updating
-
-To update the list of packages from nongnu (ELPA),
-
-1. Run `./update-nongnu`.
-2. Check for evaluation errors:
-     # "../../../../../" points to the default.nix from root of Nixpkgs tree
-     env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../../ -A emacs.pkgs.nongnuPackages
-3. Run `git commit -m "nongnu-packages $(date -Idate)" -- nongnu-generated.nix`
-
-*/
-
 { lib, pkgs, buildPackages }:
 
 self: let