manual: add "Emacs" section to manual

This gives some basics on configuring Emacs within Nix. The
configuration is fairly long just to give a good idea of what’s going
on. I can trim out some of it if it’s not necessary. Note that there
is already a section for Emacs in the NixOS manual. However, this is
aimed at avoiding using modules altogether to make things easier for
non-NixOS users. This configuration should work on NixOS anyway,
however.

Fixes #24243
Fixes #19956

1 files changed, 136 insertions, 0 deletions

diff --git a/doc/package-notes.xml b/doc/package-notes.xml
index 0f148f5c898a..33a61f31938c 100644
--- a/doc/package-notes.xml
+++ b/doc/package-notes.xml
@@ -516,4 +516,140 @@ to your configuration, rebuild, and run the game with
 
 </section>
 
+<section xml:id="sec-emacs">
+
+<title>Emacs</title>
+
+<section xml:id="sec-emacs-config">
+
+<title>Configuring Emacs</title>
+
+<para>
+  The Emacs package comes with some extra helpers to make it easier to
+  configure. <varname>emacsWithPackages</varname> 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
+  <literal>company</literal>, <literal>counsel</literal>,
+  <literal>flycheck</literal>, <literal>ivy</literal>,
+  <literal>magit</literal>, <literal>projectile</literal>, and
+  <literal>use-package</literal> you could use this as a
+  <filename>~/.config/nixpkgs/config.nix</filename> override:
+</para>
+
+<screen>
+{
+  packageOverrides = pkgs: with pkgs; {
+    myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
+      company
+      counsel
+      flycheck
+      ivy
+      magit
+      projectile
+      use-package
+    ]));
+  }
+}
+</screen>
+
+<para>
+  You can install it like any other packages via <command>nix-env -iA
+  myEmacs</command>. However, this will only install those packages.
+  It will not <literal>configure</literal> 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
+  provide a <filename>default.el</filename> file in
+  <filename>/share/emacs/site-start/</filename>. Emacs knows to load
+  this file automatically when it starts.
+</para>
+
+<screen>
+{
+  packageOverrides = pkgs: with pkgs; rec {
+    myEmacsConfig = writeText "default.el" ''
+;; initialize package
+
+(require 'package)
+(package-initialize 'noactivate)
+(eval-when-compile
+  (require 'use-package))
+
+;; load some packages
+
+(use-package company
+  :bind ("&lt;C-tab&gt;" . company-complete)
+  :diminish company-mode
+  :commands (company-mode global-company-mode)
+  :defer 1
+  :config
+  (global-company-mode))
+
+(use-package counsel
+  :commands (counsel-descbinds)
+  :bind (([remap execute-extended-command] . counsel-M-x)
+         ("C-x C-f" . counsel-find-file)
+         ("C-c g" . counsel-git)
+         ("C-c j" . counsel-git-grep)
+         ("C-c k" . counsel-ag)
+         ("C-x l" . counsel-locate)
+         ("M-y" . counsel-yank-pop)))
+
+(use-package flycheck
+  :defer 2
+  :config (global-flycheck-mode))
+
+(use-package ivy
+  :defer 1
+  :bind (("C-c C-r" . ivy-resume)
+         ("C-x C-b" . ivy-switch-buffer)
+         :map ivy-minibuffer-map
+         ("C-j" . ivy-call))
+  :diminish ivy-mode
+  :commands ivy-mode
+  :config
+  (ivy-mode 1))
+
+(use-package magit
+  :defer
+  :if (executable-find "git")
+  :bind (("C-x g" . magit-status)
+         ("C-x G" . magit-dispatch-popup))
+  :init
+  (setq magit-completing-read-function 'ivy-completing-read))
+
+(use-package projectile
+  :commands projectile-mode
+  :bind-keymap ("C-c p" . projectile-command-map)
+  :defer 5
+  :config
+  (projectile-global-mode))
+    '';
+    myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
+      (runCommand "default.el" {} ''
+mkdir -p $out/share/emacs/site-lisp
+cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
+'')
+      company
+      counsel
+      flycheck
+      ivy
+      magit
+      projectile
+      use-package
+    ]));
+  };
+}
+</screen>
+
+<para>
+  This provides a fairly full Emacs start file. It will load in
+  addition to the user's presonal config. You can always disable it by
+  passing <command>-q</command> to the Emacs command.
+</para>
+
+</section>
+
+</section>
+
 </chapter>