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] 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 {