From b55f26c65f4ca0e80bd0f3c6436333f054acf6d6 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Tue, 16 May 2023 12:41:39 -0400
Subject: [PATCH] Improve `nix-env --delete-generations` docs

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 .../command-ref/nix-env/delete-generations.md | 59 ++++++++++++++++---
 1 file changed, 50 insertions(+), 9 deletions(-)

diff --git a/doc/manual/src/command-ref/nix-env/delete-generations.md b/doc/manual/src/command-ref/nix-env/delete-generations.md
index 92cb7f0d9..d828a5b9e 100644
--- a/doc/manual/src/command-ref/nix-env/delete-generations.md
+++ b/doc/manual/src/command-ref/nix-env/delete-generations.md
@@ -9,14 +9,39 @@
 # Description
 
 This operation deletes the specified generations of the current profile.
-The generations can be a list of generation numbers, the special value
-`old` to delete all non-current generations, a value such as `30d` to
-delete all generations older than the specified number of days (except
-for the generation that was active at that point in time), or a value
-such as `+5` to keep the last `5` generations ignoring any newer than
-current, e.g., if `30` is the current generation `+5` will delete
-generation `25` and all older generations. Periodically deleting old
-generations is important to make garbage collection effective.
+
+*generations* can be a one of the following:
+
+- <span id="generations-list">`<number>...`</span>:\
+  A list of generation numbers, each one a separate command-line argument.
+
+  Delete exactly the profile generations given by their generation number.
+  Deleting the current generation is not allowed.
+
+- The special value <span id="generations-old">`old`</span>
+
+  Delete all generations older than the current one.
+
+- <span id="generations-days">`<days>d`</span>:\
+  The last *days* days
+
+  *Example*: `30d`
+
+  Delete all generations older than *days* days.
+  The generation that was active at that point in time is excluded, and will not be deleted.
+
+- <span id="generations-count">`+<count>`</span>:\
+  The last *count* generations up to the present
+
+  *Example*: `+5`
+
+  Keep the last *count* generations, along with any newer than current.
+
+Periodically deleting old generations is important to make garbage collection
+effective.
+The is because profiles are also garbage collection roots — any [store object] reachable from a profile is "alive" and ineligible for deletion.
+
+[store object]: @docroot@/glossary.md#gloss-store-object
 
 {{#include ./opt-common.md}}
 
@@ -28,19 +53,35 @@ generations is important to make garbage collection effective.
 
 # Examples
 
+## Delete explicit generation numbers
+
 ```console
 $ nix-env --delete-generations 3 4 8
 ```
 
+Delete the generations numbered 3, 4, and 8, so long as the current active generation is not any of those.
+
+## Keep most-recent by count count
+
 ```console
 $ nix-env --delete-generations +5
 ```
 
+Suppose `30` is the current generation, and we currently have generations numbered `20` through `32`.
+
+Then this command will delete generations `20` through `25` (`<= 30 - 5`),
+and keep generations `26` through `31` (`> 30 - 5`).
+
+## Keep most-recent in days
+
 ```console
 $ nix-env --delete-generations 30d
 ```
 
+This command will delete all generations older than 30 days, except for the generation that was active 30 days ago (if it currently exists).
+
+## Delete all older
+
 ```console
 $ nix-env --profile other_profile --delete-generations old
 ```
-