From 2437f8e4e05a950acf9e1e66df64eb65c2a4c3ca Mon Sep 17 00:00:00 2001
From: Felix Stupp <felix.stupp@banananet.work>
Date: Fri, 23 Aug 2024 11:41:21 +0200
Subject: [PATCH 1/2] programs.texlive: extend documentation of options
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The options were barely documented until now, making it unnecessarily hard for people even somewhat familiar with other, similar modules to use this one.
This is especially because, intuitively, `packageSet` & `extraPackages` can be misunderstood
and neither of their descriptions described their advantages.
The enable option did not explain the module‘s purpose.
I heavily expanded the option’s descriptions which hopefully makes this module useable to newcomers without resorting to look into the Nix code of the module.
---
 modules/programs/texlive.nix | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/modules/programs/texlive.nix b/modules/programs/texlive.nix
index bd17025d4..c894da7fd 100644
--- a/modules/programs/texlive.nix
+++ b/modules/programs/texlive.nix
@@ -14,12 +14,25 @@ in {
 
   options = {
     programs.texlive = {
-      enable = mkEnableOption "TeX Live";
+      enable = mkEnableOption ''
+        TeX Live package customization.
+
+        This module allows you to select which texlive packages you want to install.
+        Start by exteding {option}`programs.texlive.extraPackages`.
+      '';
 
       packageSet = mkOption {
         default = pkgs.texlive;
-        defaultText = literalExpression "pkgs.texlive";
-        description = "TeX Live package set to use.";
+        defaultText = literalExpression ''
+          pkgs.texlive  # corresponds to packages in pkgs.texlivePackages
+        '';
+        description = ''
+          TeX Live package set to use.
+
+          This is used in the option {option}`programs.texlive.extraPackages`.
+          Normally you do not want to change this from the default
+          except if you want to use texlive packages from a different nixpkgs release than your config’s default.
+        '';
       };
 
       extraPackages = mkOption {
@@ -28,7 +41,15 @@ in {
         example = literalExpression ''
           tpkgs: { inherit (tpkgs) collection-fontsrecommended algorithms; }
         '';
-        description = "Extra packages available to TeX Live.";
+        description = ''
+          Extra packages which should be appended.
+
+          {option}`programs.texlive.packageSet` will be passed to this function.
+          In case you changed your `packageSet`,
+          you can find all available packages to select from
+          in nixpkgs under `pkgs.texlivePackages`,
+          see [here to search for them in the latest release](https://search.nixos.org/packages?type=packages&query=texlivePackages.).
+        '';
       };
 
       package = mkOption {

From dc8e8ce466ea049b774fccd8be92bf1809017d62 Mon Sep 17 00:00:00 2001
From: Felix Stupp <felix.stupp@banananet.work>
Date: Fri, 23 Aug 2024 12:36:18 +0200
Subject: [PATCH 2/2] programs.texlive: further increase docs (TODO squash)

---
 modules/programs/texlive.nix | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/modules/programs/texlive.nix b/modules/programs/texlive.nix
index c894da7fd..211a89ba3 100644
--- a/modules/programs/texlive.nix
+++ b/modules/programs/texlive.nix
@@ -17,8 +17,12 @@ in {
       enable = mkEnableOption ''
         TeX Live package customization.
 
-        This module allows you to select which texlive packages you want to install.
-        Start by exteding {option}`programs.texlive.extraPackages`.
+        This module allows you to select which `pkgs.texlivePackages.*` you want to install.
+        Start by editing {option}`programs.texlive.extraPackages`.
+
+        If one of the pre-built common environments already suits you
+        (e.g. `pkgs.texliveFull` or `pkgs.texliveMedium`),
+        you do not need to use this module.
       '';
 
       packageSet = mkOption {
@@ -39,7 +43,16 @@ in {
         default = tpkgs: { inherit (tpkgs) collection-basic; };
         defaultText = "tpkgs: { inherit (tpkgs) collection-basic; }";
         example = literalExpression ''
-          tpkgs: { inherit (tpkgs) collection-fontsrecommended algorithms; }
+          tpkgs: with tpkgs; { # E.g. you can select from & combine
+            # pre-built environments (e.g. this equals pkgs.texliveSmall)
+            inherit scheme-small;
+            # collection of smaller packages (similar granularity to packages in Linux distros like Debian)
+            inherit collection-fontsrecommended;
+            # or individual tex packages (corresponds in general to packages from CTAN & co.).
+            inherit algorithms;
+            # You can mix them however you see fit (overlaps should be no problem)
+            inherit scheme-bookpub bibtex8 latexmk;
+          }
         '';
         description = ''
           Extra packages which should be appended.
@@ -48,7 +61,7 @@ in {
           In case you changed your `packageSet`,
           you can find all available packages to select from
           in nixpkgs under `pkgs.texlivePackages`,
-          see [here to search for them in the latest release](https://search.nixos.org/packages?type=packages&query=texlivePackages.).
+          search [here for them](https://search.nixos.org/packages?type=packages&query=texlivePackages.).
         '';
       };
 
@@ -67,6 +80,7 @@ in {
         + " 'programs.texlive.extraPackages'.";
     }];
 
+    # note: cfg.enable states that this module’s only purpose is to customize the texlive environment
     home.packages = [ cfg.package ];
 
     programs.texlive.package = texlive.combine texlivePkgs;