docs(treewide): Fix typos, rewrite for clarity, add more markdown for…

…matting to option descriptions. (#400) Signed-off-by: Fernando Rodrigues <[email protected]>
nix-community · Nov 9, 2024 · f33173b · f33173b
1 parent 2936685
commit f33173b
Show file tree

Hide file tree

Showing 20 changed files with 254 additions and 246 deletions.
diff --git a/docs/manual/introduction.md b/docs/manual/introduction.md
@@ -1,7 +1,6 @@
 # Introduction {#intro}
-To get started it may be helpful to check out the
-[getting started section in the README](https://github.com/nix-community/plasma-manager#getting-started).
-This gives a couple examples on how you can get started using plasma-manager,
-either using a flake or traditional nix-channels.
+To get started, check out the [**getting started** section in the README](https://github.com/nix-community/plasma-manager#getting-started).
+There are a couple of examples on how you can get started using `plasma-manager`,
+using either a flake or traditional Nix channels.
 
-More details may be available here in the future!
+More details may be available here in the future!
diff --git a/docs/manual/preface.md b/docs/manual/preface.md
@@ -1,10 +1,10 @@
 # Preface {#preface}
-Plasma-Manager is a [Home Manager](https://github.com/nix-community/home-manager)
-module which has as a goal to be able to configure as much of KDE plasma as
-possible, using nix.
+Plasma Manager is a [Home Manager](https://github.com/nix-community/home-manager)
+module capable of configuring as much of KDE Plasma as
+possible, using [Nix](https://nixos.org).
 
 The project has progressed a lot lately, to the extent where
-[most of the configuration options present in KDE Plasma 6 are configurable through plasma-manager](https://github.com/nix-community/plasma-manager#whats-supported).
+[most of the configuration options present in KDE Plasma 6 are configurable through `plasma-manager`](https://github.com/nix-community/plasma-manager#whats-supported).
 
-The main focus of the project has been on KDE plasma 6 for a little while now,
-but it's also possible to use it to some extent on plasma 5 as well.
+The main focus of the project has been on KDE Plasma 6 for a little while now,
+but it's also possible to use it to some extent on Plasma 5 as well.
diff --git a/modules/apps/ghostwriter.nix b/modules/apps/ghostwriter.nix
@@ -52,7 +52,7 @@ let
         type = matchingPrefer;
         default = "default";
         description = ''
-          Whether the font matching process prefers exact matches, of best quality matches.
+          Whether the font matching process prefers exact matches, or best quality matches.
 
           `default` corresponds to not setting any enum flag, and `exact` and `quality`
           correspond to `PreferMatch` and `PreferQuality` enum flags respectively.
@@ -72,7 +72,7 @@ let
         type = lib.types.bool;
         default = false;
         description = ''
-          If set to true, this font will try to avoid subpixel antialiasing.
+          If set to `true`, this font will try to avoid subpixel antialiasing.
 
           Corresponds to the `NoSubpixelAntialias` enum flag.
         '';
@@ -81,7 +81,7 @@ let
         type = lib.types.bool;
         default = false;
         description = ''
-          If set to true, this font will not try to find a substitute font when encountering missing glyphs.
+          If set to `true`, this font will not try to find a substitute font when encountering missing glyphs.
 
           Corresponds to the `NoFontMerging` enum flag.
         '';
@@ -90,7 +90,7 @@ let
         type = lib.types.bool;
         default = false;
         description = ''
-          If set to true, this font will not try to apply shaping rules that may be required for some scripts
+          If set to `true`, this font will not try to apply shaping rules that may be required for some scripts
           (e.g. Indic scripts), increasing performance if these rules are not required.
 
           Corresponds to the `PreferNoShaping` enum flag.
@@ -130,7 +130,7 @@ let
         description = ''
           The style hint of this font.
 
-          See https://doc.qt.io/qt-6/qfont.html#StyleHint-enum for more.
+          See https://doc.qt.io/qt-6/qfont.html#StyleHint-enum for more information.
         '';
       };
       weight = lib.mkOption {
@@ -139,7 +139,7 @@ let
         description = ''
           The weight of the font, either as a number between 1 to 1000 or as a pre-defined weight string.
 
-          See https://doc.qt.io/qt-6/qfont.html#Weight-enum for more.
+          See https://doc.qt.io/qt-6/qfont.html#Weight-enum for more information.
         '';
       };
       style = lib.mkOption {
@@ -265,9 +265,9 @@ in
           nullable = true;
           example = "pkgs.kdePackages.ghostwriter";
           extraDescription = ''
-            Use `pkgs.libsForQt5.ghostwriter` in Plasma5 and
-            `pkgs.kdePackages.ghostwriter` in Plasma6. Use
-            `null` if home-manager should not install GhostWriter.
+            Use `pkgs.libsForQt5.ghostwriter` for Plasma 5 and
+            `pkgs.kdePackages.ghostwriter` for Plasma 6. Use
+            `null` if `home-manager` should not install Ghostwriter.
           '';
         };
 
@@ -347,7 +347,7 @@ in
                   ]
                   (
                     lib.lists.findFirstIndex (x: x == focusMode)
-                      (throw "editor.styling.focusMode: Value ${focusMode} isn't present in the enum. This is a bug")
+                      (throw "editor.styling.focusMode: Value ${focusMode} isn't present in the enum. This is a bug.")
                       enumVals
                   );
           };
@@ -580,8 +580,8 @@ in
         type = with lib.types; attrsOf path;
         default = { };
         description = ''
-          Custom themes to be added to the installation. The key is their name.
-          Choose them in `programs.ghostwriter.theme.name`.
+          Custom themes to be added to the installation. The attribute key is mapped to their name.
+          Choose them from `programs.ghostwriter.theme.name`.
         '';
       };
     };

diff --git a/modules/apps/kate/default.nix b/modules/apps/kate/default.nix
@@ -38,7 +38,7 @@ let
     else
       lib.lists.findFirstIndex (
         x: x == value
-      ) (throw "getIndexFromEnum (kate): Value ${value} isn't present in the enum. This is a bug") enum;
+      ) (throw "getIndexFromEnum (kate): Value ${value} isn't present in the enum. This is a bug.") enum;
 
   qfont = import ../../../lib/qfont.nix { inherit lib; };
 
@@ -59,7 +59,7 @@ let
         type = matchingPrefer;
         default = "default";
         description = ''
-          Whether the font matching process prefers exact matches, of best quality matches.
+          Whether the font matching process prefers exact matches, or best quality matches.
 
           `default` corresponds to not setting any enum flag, and `exact` and `quality`
           correspond to `PreferMatch` and `PreferQuality` enum flags respectively.
@@ -79,7 +79,7 @@ let
         type = lib.types.bool;
         default = false;
         description = ''
-          If set to true, this font will try to avoid subpixel antialiasing.
+          If set to `true`, this font will try to avoid subpixel antialiasing.
 
           Corresponds to the `NoSubpixelAntialias` enum flag.
         '';
@@ -88,7 +88,7 @@ let
         type = lib.types.bool;
         default = false;
         description = ''
-          If set to true, this font will not try to find a substitute font when encountering missing glyphs.
+          If set to `true`, this font will not try to find a substitute font when encountering missing glyphs.
 
           Corresponds to the `NoFontMerging` enum flag.
         '';
@@ -97,7 +97,7 @@ let
         type = lib.types.bool;
         default = false;
         description = ''
-          If set to true, this font will not try to apply shaping rules that may be required for some scripts
+          If set to `true`, this font will not try to apply shaping rules that may be required for some scripts
           (e.g. Indic scripts), increasing performance if these rules are not required.
 
           Corresponds to the `PreferNoShaping` enum flag.
@@ -237,7 +237,7 @@ in
 {
   options.programs.kate = {
     enable = lib.mkEnableOption ''
-      Enable configuration management for kate.
+      Enable configuration management for Kate, the KDE Advanced Text Editor.
     '';
 
     package =
@@ -250,18 +250,16 @@ in
           nullable = true;
           example = "pkgs.libsForQt5.kate";
           extraDescription = ''
-            Which kate package to install. Use `pkgs.libsForQt5.kate` in Plasma5 and
-            `pkgs.kdePackages.kate` in Plasma6. Use `null` if home-manager should not install kate
-            (use this if you want to manage the settings of this user of a system-wide kate
-            installation).
+            Which Kate package to be installed by `home-manager`. Use `pkgs.libsForQt5.kate` for Plasma 5 and
+            `pkgs.kdePackages.kate` for Plasma 6. Use `null` if `home-manager` should not install Kate.
           '';
         };
 
     # ==================================
     #     INDENTATION
     editor = {
       tabWidth = lib.mkOption {
-        description = "The width of a single tab (''\t) sign (in number of spaces).";
+        description = "The width of a single tab (`\t`) sign (in number of spaces).";
         default = 4;
         type = lib.types.int;
       };
@@ -280,7 +278,7 @@ in
 
       indent.autodetect = lib.mkOption {
         description = ''
-          Whether kate should try to detect indentation for each given file and not impose default indentation settings.
+          Whether Kate should try to detect indentation for each given file and not impose default indentation settings.
         '';
         default = true;
         type = lib.types.bool;
@@ -311,7 +309,7 @@ in
       };
 
       indent.undoByShiftTab = lib.mkOption {
-        description = "Whether to unindent the current line by one level with the shortcut Shift+Tab";
+        description = "Whether to unindent the current line by one level with the shortcut Shift+Tab.";
         default = true;
         type = lib.types.bool;
       };
@@ -360,11 +358,12 @@ in
     src = lib.mkOption {
       description = ''
         The path of a theme file for the KDE editor (not the window color scheme).
-        Obtain a custom one by using the GUI settings in kate. If you want to use a system-wide
+        Obtain a custom one by using the GUI settings in Kate. If you want to use a system-wide
         editor color scheme set this path to null. If you set the metadata.name entry in the file
         to a value that matches the name of a system-wide color scheme undesired behaviour may
         occur. The activation will fail if a theme with the filename `<name of your theme>.theme`
-        already exists.'';
+        already exists.
+      '';
       type = lib.types.nullOr lib.types.path;
       default = null;
     };
@@ -419,9 +418,9 @@ in
     default = null;
     type = lib.types.nullOr lib.types.attrs;
     description = ''
-      Add more lsp server settings here. Check out the format on the
-      [KDE page](https://docs.kde.org/stable5/en/kate/kate/kate-application-plugin-lspclient.html).
-      Note that these are only the settings, the packages have to be installed separately.
+      Add more LSP server settings here. Check out the format on the
+      [Kate Documentation](https://docs.kde.org/stable5/en/kate/kate/kate-application-plugin-lspclient.html).
+      Note that these are only the settings; the appropriate packages have to be installed separately.
     '';
   };
 

diff --git a/modules/apps/konsole.nix b/modules/apps/konsole.nix
@@ -34,7 +34,7 @@ let
         example = "Catppuccin-Mocha";
         description = ''
           Color scheme the profile will use. You can check the files you can
-          use in ~/.local/share/konsole or /run/current-system/share/konsole.
+          use in `$HOME/.local/share/konsole` or `/run/current-system/sw/share/konsole`.
           You might also add a custom color scheme using
           `programs.konsole.customColorSchemes`.
         '';
@@ -70,7 +70,7 @@ let
           example = 12;
           description = ''
             Size of the font.
-            Needs a font to be set due to konsole limitations.
+            Due to Konsole limitations, only a limited range of sizes is possible.
           '';
         };
       };
@@ -89,16 +89,16 @@ in
 {
   options.programs.konsole = {
     enable = lib.mkEnableOption ''
-      Enable configuration management for Konsole.
+      Enable configuration management for Konsole, the KDE Terminal.
     '';
 
     defaultProfile = lib.mkOption {
       type = with lib.types; nullOr str;
       default = null;
       example = "Catppuccin";
       description = ''
-        The name of the konsole profile file to use by default.
-        To see what options you have, just take a look at ~/.local/share/konsole/
+        The name of the Konsole profile file to use by default.
+        To see what options you have, take a look at `$HOME/.local/share/konsole`
       '';
     };
 
@@ -114,7 +114,7 @@ in
       type = with lib.types; attrsOf path;
       default = { };
       description = ''
-        Custom color schemes to be added to the installation. The key is their name.
+        Custom color schemes to be added to the installation. The attribute key maps to their name.
         Choose them in any profile with `profiles.<profile>.colorScheme = <name>`;
       '';
     };
@@ -124,16 +124,16 @@ in
       default = null;
       example = "Krita dark orange";
       description = ''
-        The colour scheme of the UI. Leave this setting at `null` in order to
-        not override the systems default scheme for for this application.
+        The color scheme of the UI. Leave this setting at `null` in order to
+        not override the system's default scheme for for this application.
       '';
     };
 
     extraConfig = lib.mkOption {
       type = with lib.types; nullOr (attrsOf (attrsOf basicSettingsType));
       default = null;
       description = ''
-        Extra config to add to konsolerc.
+        Extra config to add to the `konsolerc`.
       '';
     };
   };

diff --git a/modules/apps/okular.nix b/modules/apps/okular.nix
@@ -42,25 +42,25 @@ with lib.types;
     #     GENERAL
     general = {
       smoothScrolling = lib.mkOption {
-        description = "Use smooth scrolling.";
+        description = "Whether to use smooth scrolling.";
         default = null;
         type = nullOr bool;
       };
 
       showScrollbars = lib.mkOption {
-        description = "Show scrollbars.";
+        description = "Whether to show scrollbars in the document viewer.";
         default = null;
         type = nullOr bool;
       };
 
       openFileInTabs = lib.mkOption {
-        description = "Open files in tabs.";
+        description = "Whether to open files in tabs.";
         default = null;
         type = nullOr bool;
       };
 
       viewContinuous = lib.mkOption {
-        description = "Open in continous mode by default.";
+        description = "Whether to open in continous mode by default.";
         default = null;
         type = nullOr bool;
       };
@@ -108,14 +108,14 @@ with lib.types;
       mouseMode = lib.mkOption {
         description = ''
           Changes what the mouse does.
-          See https://docs.kde.org/stable5/en/okular/okular/menutools.html for
-          the full description.
-          Browse - Click-and-drag with left mouse button.
-          Zoom - Zoom in with left mouse button. Reset zoom with right mouse button.
-          Rectangle Selection - Draw area selection with left mouse button. Display options with right mouse button.
-          Text Selection - Select text with left mouse button. Display options with right mouse button.
-          Table Selection - Similar to text selection but allows for transforming the document into a table.
-          Magnifier - Activates the magnifier with left mouse button.
+          See the [Okular Documentation](https://docs.kde.org/stable5/en/okular/okular/menutools.html) for the full description.
+
+          - `Browse`: Click-and-drag with left mouse button.
+          - `Zoom`: Zoom in with left mouse button. Reset zoom with right mouse button.
+          - `RectSelect`: Draw area selection with left mouse button. Display options with right mouse button.
+          - `TextSelect`: Select text with left mouse button. Display options with right mouse button.
+          - `TableSelect`: Similar to text selection but allows for transforming the document into a table.
+          - `Magnifier`: Activates the magnifier with left mouse button.
         '';
         default = null;
         type = nullOr (enum [
@@ -134,7 +134,7 @@ with lib.types;
     #     ACCESSIBILITY
     accessibility = {
       highlightLinks = lib.mkOption {
-        description = "Draw borders around links.";
+        description = "Whether to draw borders around links.";
         default = null;
         type = nullOr bool;
       };
@@ -206,13 +206,13 @@ with lib.types;
     #     PERFORMANCE
     performance = {
       enableTransparencyEffects = lib.mkOption {
-        description = "Enable transparancey effects. This may increase CPU usage.";
+        description = "Whether to enable transparancy effects. This may increase CPU usage.";
         default = null;
         type = nullOr bool;
       };
 
       memoryUsage = lib.mkOption {
-        description = "Memory usage of Okular. This impacts the speed performance of Okular as it determines how much computation results are kept in memory and not recomputed.";
+        description = "Memory usage profile for Okular. This may impact the speed performance of Okular, as it determines how many computation results are kept in memory.";
         default = null;
         type = nullOr (enum [
           "Low"

diff --git a/modules/default.nix b/modules/default.nix
@@ -23,6 +23,6 @@
   ];
 
   options.programs.plasma.enable = lib.mkEnableOption ''
-    Enable configuration management for KDE Plasma.
+    Whether to enable declarative configuration options for the KDE Plasma Desktop.
   '';
 }