From 52d0a6dc635c6ad81cb32bbd870f8776f77408b1 Mon Sep 17 00:00:00 2001
From: Jason Goemaat <jason.goemaat@gmail.com>
Date: Wed, 20 Mar 2024 13:43:13 -0500
Subject: [PATCH] Added how to doc showing nix-shell and editing config

---
 docs/src/SUMMARY.md |  2 +-
 docs/src/how-to.md  | 76 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/how-to.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 2e26c9ee..3ccbd3bf 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -7,7 +7,7 @@
 - [Installation](./install.md)
 - [Design](./design.md)
 - [Building](./building.md)
-- [How-To]()
+- [How-To](./how-to.md)
 - [Troubleshooting](./troubleshooting/README.md)
   - [Recovery Shell](./troubleshooting/recovery-shell.md)
 
diff --git a/docs/src/how-to.md b/docs/src/how-to.md
new file mode 100644
index 00000000..9e0faaa8
--- /dev/null
+++ b/docs/src/how-to.md
@@ -0,0 +1,76 @@
+# How-to
+
+## Using packages in nix-shell
+
+`nix-shell` can be used to run a temporary shell or command that uses packages
+you don't want to install into your system permanently, or to use other
+versions of packages than you have installed.  For example there is a
+'cowsay' command that is like echo but with an ascii cow saying the words.
+If you type `cowsay Hello, world!`, you will get an error that will tell you
+the cowsay command is provided by multiple packages and show you the nix-shell
+commands to use them:
+
+```
+[nixos@nixos:/mnt/c/t/nix]$ cowsay moo
+The program 'cowsay' is not in your PATH. It is provided by several packages.
+You can make it available in an ephemeral shell by typing one of the following:
+  nix-shell -p cowsay
+  nix-shell -p neo-cowsay
+
+[nixos@nixos:/mnt/c/t/nix]$ nix-shell -p cowsay
+this path will be fetched (0.01 MiB download, 0.05 MiB unpacked):
+  /nix/store/pjaiq8m9rjgj9akjgmbzmz86cvxwsyqm-cowsay-3.7.0
+copying path '/nix/store/pjaiq8m9rjgj9akjgmbzmz86cvxwsyqm-cowsay-3.7.0' from 'https://cache.nixos.org'...
+
+[nix-shell:/mnt/c/t/nix]$ cowsay moo
+ _____
+< moo >
+ -----
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+
+[nix-shell:/mnt/c/t/nix]$ exit
+exit
+
+[nixos@nixos:/mnt/c/t/nix]$
+```
+
+You can also specify multiple packages and specify a `--run` parameter to run
+a single command and exit instead of leaving you in a shell:
+
+```
+nix-shell -p cowsay lolcat --run "cowsay Hello, cat! | lolcat"
+```
+
+
+## System Packages
+
+To add packages, edit `/etc/nixos/configuration.nix` using sudo.   You
+can use the `nano` editor which comes installed and uses CTRL+S to save
+and CTRL+X to exit:
+
+```
+sudo nano /etc/nixos/configuration.nix
+```
+
+At the bottom you can add system packages to be available in the system:
+
+```
+  environment.systemPackages = [ pkgs.cowsay pkgs.lolcat ];
+}
+```
+
+To switch to the new configuration use this:
+
+```
+sudo nixos-rebuild switch
+```
+
+Now you can use the commands provided in those packages by default:
+
+```
+cowsay Hello, NixOS! | lolcat
+```