From 35536fc6d621a084b04a70a6478db2aebbe828ed Mon Sep 17 00:00:00 2001
From: nbelakovski <nbelakovski@users.noreply.github.com>
Date: Mon, 11 Mar 2024 23:07:12 -0700
Subject: [PATCH] docs: update beets and description of overriding packages

The beets package no longer has the "enableCheck" option so this was
confusing. Also the word override was used to mean two different
things so I modified the FAQ to use the word "change" and linked to
documentation regarding package overrides.
---
 docs/manual/faq.md                            |  2 +-
 ...age-module.md => change-package-module.md} | 30 ++++++++++++++++---
 modules/programs/beets.nix                    |  4 +--
 3 files changed, 29 insertions(+), 7 deletions(-)
 rename docs/manual/faq/{override-package-module.md => change-package-module.md} (53%)

diff --git a/docs/manual/faq.md b/docs/manual/faq.md
index bc50174d5..ea308f788 100644
--- a/docs/manual/faq.md
+++ b/docs/manual/faq.md
@@ -6,5 +6,5 @@ faq/session-variables.md
 faq/multiple-users-machines.md
 faq/ca-desrt-dconf.md
 faq/unstable.md
-faq/override-package-module.md
+faq/change-package-module.md
 ```
diff --git a/docs/manual/faq/override-package-module.md b/docs/manual/faq/change-package-module.md
similarity index 53%
rename from docs/manual/faq/override-package-module.md
rename to docs/manual/faq/change-package-module.md
index 60b847625..bcb943baf 100644
--- a/docs/manual/faq/override-package-module.md
+++ b/docs/manual/faq/change-package-module.md
@@ -1,4 +1,4 @@
-# How do I override the package used by a module? {#_how_do_i_override_the_package_used_by_a_module}
+# How do I change the package used by a module? {#_how_do_i_change_the_package_used_by_a_module}
 
 By default Home Manager will install the package provided by your chosen
 `nixpkgs` channel but occasionally you might end up needing to change
@@ -6,13 +6,35 @@ this package. This can typically be done in two ways.
 
 1.  If the module provides a `package` option, such as
     `programs.beets.package`, then this is the recommended way to
-    perform the override. For example,
+    perform the change. For example,
 
     ``` nix
-    programs.beets.package = pkgs.beets.override { enableCheck = true; };
+    programs.beets.package = pkgs.beets.override { pluginOverrides = { beatport.enable = false; }; };
     ```
 
-2.  If no `package` option is available then you can typically override
+    See [Nix pill 17](https://nixos.org/guides/nix-pills/nixpkgs-overriding-packages.html)
+    for more information on package overrides. Alternatively, if you want
+    to use the `beets` package from Nixpkgs unstable, then a configuration like
+
+    ``` nix
+    { pkgs, config, ... }:
+
+    let
+
+      pkgsUnstable = import <nixpkgs-unstable> {};
+
+    in
+
+    {
+      programs.beets.package = pkgsUnstable.beets;
+
+      # …
+    }
+    ```
+
+    should work OK.
+
+3.  If no `package` option is available then you can typically change
     the relevant package using an
     [overlay](https://nixos.org/nixpkgs/manual/#chap-overlays).
 
diff --git a/modules/programs/beets.nix b/modules/programs/beets.nix
index dab98c301..5a2b97f33 100644
--- a/modules/programs/beets.nix
+++ b/modules/programs/beets.nix
@@ -32,8 +32,8 @@ in {
         type = types.package;
         default = pkgs.beets;
         defaultText = literalExpression "pkgs.beets";
-        example =
-          literalExpression "(pkgs.beets.override { enableCheck = true; })";
+        example = literalExpression
+          "(pkgs.beets.override { pluginOverrides = { beatport.enable = false; }; })";
         description = ''
           The `beets` package to use.
           Can be used to specify extensions.