emacsPackages: update documentation

doc/languages-frameworks/elisp.section.md

@@ -0,0 +1,124 @@
+# Emacs Lisp {#emacs-lisp}
+
+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.

doc/languages-frameworks/index.md

@@ -64,6 +64,7 @@ dart.section.md
 dhall.section.md
 dlang.section.md
 dotnet.section.md
+elisp.section.md
 emscripten.section.md
 gnome.section.md
 go.section.md

doc/packages/emacs.section.md

@@ -1,8 +1,16 @@
 # Emacs {#sec-emacs}
 
+[Emacs](https://www.gnu.org/software/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 leverages Emacs 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, without relying on Emacs to download and install them.
+
+For instance, by writing the code below at `~/.config/nixpkgs/config.nix`, the Elisp packages `company` `counsel`, `flycheck`, `ivy`,`magit`, `projectile`, and `use-package` are installed:
 
 ```nix
 {
@@ -20,7 +28,16 @@ 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.
+This package can be installed like any other, via `nix-env -iA myEmacs`.
+
+However, this expression merely installs the package. 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 loads this file automatically when it starts.
 
 ```nix
 {
@@ -97,9 +114,14 @@ You can install it like any other packages via `nix-env -iA myEmacs`. However, t
 }
 ```
 
-This provides a fairly full Emacs start file. It will load in addition to the user's personal config. You can always disable it by passing `-q` to the Emacs command.
+This provides a fairly full Emacs start file. It will be loaded in addition to the user's personal config. It is always possible to disable it, by passing `-q` as a command line argument to Emacs.
+
+Sometimes `emacs.pkgs.withPackages` is not enough, as this package set imposes some priorities over their packages (with the lowest priority assigned to GNU-devel ELPA, and the highest for packages manually defined in `pkgs/applications/editors/emacs/elisp-packages/manual-packages`).
+
+But it is not possible to control these priorities when some package is installed as a dependency. The overrides can be done on a per-package-basis, providing all the required dependencies manually. However this procedure is tedious and there is always a possibility that an unwanted dependency sneaks in through some other package. 
+
+A complete and pervasive override for such a package can be done via `overrideScope`.
 
-Sometimes `emacs.pkgs.withPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to GNU-devel ELPA, and the highest for packages manually defined in `pkgs/applications/editors/emacs/elisp-packages/manual-packages`). But you can't control these priorities when some package is installed as a dependency. You can override it on a per-package-basis, providing all the required dependencies manually, but it's tedious and there is always a possibility that an unwanted dependency will sneak in through some other package. To completely override such a package, you can use `overrideScope`.
 
 ```nix
 let

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