emacs-packages: Cleanup and document for overrides

This removes some stale code that was a no-op for some time and adds
some docs/examples to help people with explicitly and consistently
choosing versions of some emacs packages (to help with problems
similar to #27083).

3 files changed, 27 insertions, 5 deletions

diff --git a/doc/package-notes.xml b/doc/package-notes.xml
index 184bee089ae3..19b476597de8 100644
--- a/doc/package-notes.xml
+++ b/doc/package-notes.xml
@@ -660,6 +660,32 @@ cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
   passing <command>-q</command> to the Emacs command.
 </para>
 
+<para>
+  Sometimes <varname>emacsWithPackages</varname> is not enough, as
+  this package set has some priorities imposed on packages (with
+  the lowest priority assigned to Melpa Unstable, and the highest for
+  packages manually defined in
+  <filename>pkgs/top-level/emacs-packages.nix</filename>). But you
+  can't control this priorities when some package is installed as a
+  dependency. You can override it on 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 <varname>overrideScope</varname>.
+</para>
+
+<screen>
+overrides = super: self: rec {
+  haskell-mode = self.melpaPackages.haskell-mode;
+  ...
+};
+((emacsPackagesNgGen emacs).overrideScope overrides).emacsWithPackages (p: with p; [
+  # here both these package will use haskell-mode of our own choice
+  ghc-mod
+  dante
+])
+</screen>
+
 </section>
 
 </section>
diff --git a/pkgs/top-level/all-packages.nix b/pkgs/top-level/all-packages.nix
index ebb9831d3ff0..bb559038b3e7 100644
--- a/pkgs/top-level/all-packages.nix
+++ b/pkgs/top-level/all-packages.nix
@@ -14409,8 +14409,6 @@ with pkgs;
   emacs25Packages = emacsPackagesGen emacs25 pkgs.emacs25Packages;
 
   emacsPackagesNgGen = emacs: import ./emacs-packages.nix {
-    overrides = (config.emacsPackageOverrides or (p: {})) pkgs;
-
     inherit lib newScope stdenv;
     inherit fetchFromGitHub fetchgit fetchhg fetchurl;
     inherit emacs texinfo makeWrapper runCommand;
diff --git a/pkgs/top-level/emacs-packages.nix b/pkgs/top-level/emacs-packages.nix
index 4ff8d23424c7..57610c3827cc 100644
--- a/pkgs/top-level/emacs-packages.nix
+++ b/pkgs/top-level/emacs-packages.nix
@@ -32,9 +32,7 @@
 #   `meta` with `platforms` and `homepage` set to something you are
 #   unlikely to want to override for most packages
 
-{ overrides
-
-, lib, newScope, stdenv, fetchurl, fetchgit, fetchFromGitHub, fetchhg, runCommand
+{ lib, newScope, stdenv, fetchurl, fetchgit, fetchFromGitHub, fetchhg, runCommand
 
 , emacs, texinfo, lndir, makeWrapper
 , trivialBuild