better stow

README.md

@@ -38,6 +38,10 @@ https://github.com/user-attachments/assets/7e2db305-58bc-4b3d-9c65-7dc0461aead7
 
 ## Setup Overview
 
+> [!NOTE]
+>
+> See also [config-stow](./config-stow) for the list of stow packages.
+
 - OS: **Archlinux**
 - WM: Hyprland | **Niri**
 - Bar: Waybar | **Quickshell**

config-stow

@@ -5,46 +5,52 @@ from argparse import ArgumentParser
 from pathlib import Path
 
 BASE_PKGS = [
-    "clang",
-    "scripts",
-    "stow"
+    "clang",    # C/C++ development
+    "scripts",  # scripts & snippets
+    "stow"      # --target=~
 ]
 
+# for TUI only setups
+# e.g. servers that are accessed via SSH only
 TUI_PKGS = [
     *BASE_PKGS,
-    "fastfetch",
-    "nvim",
-    "shell",
-    "yazi"
+    "fastfetch",    # sys info
+    "nvim",         # editor
+    "shell",        # fish & .bash_profile & shell prompt
+    "yazi"          # terminal file manager
 ]
 
+# for all WMs and DEs
 GUI_BASE_PKGS = [
     *TUI_PKGS,
-    "kitty",
-    "ghostty",
-    "misc",
-    "mpv",
-    "wallpaper",
-    "kvantum",
-    "nwg-look"
+    "kitty",        # terminal emulator
+    "ghostty",      # alternative terminal emulator
+    "misc",         # miscellaneous GUI configs (e.g. *-flags)
+    "mpv",          # media player
+    "wallpaper",    # wallpapers & manager
+    "kvantum",      # qt theming
+    "nwg-look"      # gtk theming
 ]
 
+# for Hyprland setup
 HYPRLAND_PKGS = [
     *GUI_BASE_PKGS,
-    "eww",
-    "hypr",
-    "mako",
-    "rofi",
-    "waybar",
-    "wlogout"
+    "eww",      # widgets
+    "hypr",     # hypr family
+    "mako",     # notifications
+    "rofi",     # application launcher
+    "waybar",   # status bar
+    "wlogout"   # logout menu
 ]
 
+# for Niri setup
 NIRI_PKGS = [
     *GUI_BASE_PKGS,
-    "niri",
-    "quickshell",
-    "rofi",
-    "wlogout"
+    "hypr",         # for hyprlock & hypridle
+    "niri",         # wm config
+    "quickshell",   # widget & status bar & notifications & ...
+    "rofi",         # application launcher
+    "wlogout"       # logout menu
 ]
 
 PKGS = {
@@ -75,7 +81,7 @@ def switch(session: str):
 
 
 def main():
-    parser = ArgumentParser(description="Stow configuration packages.")
+    parser = ArgumentParser(description="Stow configuration packages in this repository.")
     parser.add_argument(
         "package",
         choices=PKGS.keys(),