doc/languages-frameworks/elisp.section.md: init

doc/languages-frameworks/elisp.section.md

@@ -0,0 +1,86 @@
+# 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.
+
+<!--
+TODO: add a chapter about melpaBuild and the general Elisp Nix framework
+-->
+
+## 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 `pkgs/applications/editors/emacs/elisp-packages` subdirectory we find
+the following scripts:
+
+- `update-scripts-library.sh`
+
+  This script acts 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_packagesets`
+
+    This function downloads from [`nix-community` Emacs Overlay](https://github.com/nix-community/emacs-overlay) the corresponding files.
+
+    It accepts any number of arguments. The only acceptable arguments are:
+    `elpa`, `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`.
+
+    When an argument is not recognized, the function bails out with an error
+    message.
+
+  - `test_packagesets`
+
+    This function runs a simple test that instantiates the corresponding package set.
+
+    It accepts any number of arguments. The only acceptable arguments are:
+    `elpa`, `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`.
+
+    When an argument is not recognized, the function bails out with an error
+    message.
+
+  - `commit_packagesets`
+
+    This function commits the corresponding package set, writing a short
+    commit message.
+
+    It accepts any number of arguments. The only acceptable arguments are:
+    `elpa`, `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`.
+
+    When an argument is not recognized, the function bails out with an error
+    message.
+
+- `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`.
+
+  When an argument is not recognized, the function bails out with an error
+  message.
+
+- `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