Split nix-env and nix-store documentation per-subcommand

Documentation on "classic" commands with many sub-commands are
notoriously hard to discover due to lack of overview and anchor links.
Additionally the information on common options and environment variables
is not accessible offline in man pages, and therefore often overlooked
by readers.

With this change, each sub-command of nix-store and nix-env gets its
own page in the manual (listed in the table of contents), and each own
man page.

Also, man pages for each subcommand now (again) list common options
and environment variables. While this makes each page quite long and
some common parameters don't apply, this should still make it easier
to navigate as that additional information was not accessible on the
command line at all.

It is now possible to run 'nix-store --<subcommand> --help` to display
help pages for the given subcommand.

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>

1 files changed, 20 insertions, 20 deletions

diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
index 2be55be52..bf00be84f 100644
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@@ -2,18 +2,18 @@
 
 Most Nix commands interpret the following environment variables:
 
-  - [`IN_NIX_SHELL`]{#env-IN_NIX_SHELL}\
+  - <span id="env-IN_NIX_SHELL">[`IN_NIX_SHELL`](#env-IN_NIX_SHELL)</span>\
     Indicator that tells if the current environment was set up by
     `nix-shell`. It can have the values `pure` or `impure`.
 
-  - [`NIX_PATH`]{#env-NIX_PATH}\
+  - <span id="env-NIX_PATH">[`NIX_PATH`](#env-NIX_PATH)</span>\
     A colon-separated list of directories used to look up the location of Nix
-    expressions using [paths](../language/values.md#type-path)
+    expressions using [paths](@docroot@/language/values.md#type-path)
     enclosed in angle brackets (i.e., `<path>`),
     e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
-    [`-I` option](./opt-common.md#opt-I).
+    [`-I` option](@docroot@/command-ref/opt-common.md#opt-I).
 
-    If `NIX_PATH` is not set at all, Nix will fall back to the following list in [impure](./conf-file.md#conf-pure-eval) and [unrestricted](./conf-file.md#conf-restrict-eval) evaluation mode:
+    If `NIX_PATH` is not set at all, Nix will fall back to the following list in [impure](@docroot@/command-ref/conf-file.md#conf-pure-eval) and [unrestricted](@docroot@/command-ref/conf-file.md#conf-restrict-eval) evaluation mode:
 
       1. `$HOME/.nix-defexpr/channels`
       2. `nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixpkgs`
@@ -24,7 +24,7 @@ Most Nix commands interpret the following environment variables:
 
         error: file 'nixpkgs' was not found in the Nix search path
 
-  - [`NIX_IGNORE_SYMLINK_STORE`]{#env-NIX_IGNORE_SYMLINK_STORE}\
+  - <span id="env-NIX_IGNORE_SYMLINK_STORE">[`NIX_IGNORE_SYMLINK_STORE`](#env-NIX_IGNORE_SYMLINK_STORE)</span>\
     Normally, the Nix store directory (typically `/nix/store`) is not
     allowed to contain any symlink components. This is to prevent
     “impure” builds. Builders sometimes “canonicalise” paths by
@@ -46,58 +46,58 @@ Most Nix commands interpret the following environment variables:
 
     Consult the mount 8 manual page for details.
 
-  - [`NIX_STORE_DIR`]{#env-NIX_STORE_DIR}\
+  - <span id="env-NIX_STORE_DIR">[`NIX_STORE_DIR`](#env-NIX_STORE_DIR)</span>\
     Overrides the location of the Nix store (default `prefix/store`).
 
-  - [`NIX_DATA_DIR`]{#env-NIX_DATA_DIR}\
+  - <span id="env-NIX_DATA_DIR">[`NIX_DATA_DIR`](#env-NIX_DATA_DIR)</span>\
     Overrides the location of the Nix static data directory (default
     `prefix/share`).
 
-  - [`NIX_LOG_DIR`]{#env-NIX_LOG_DIR}\
+  - <span id="env-NIX_LOG_DIR">[`NIX_LOG_DIR`](#env-NIX_LOG_DIR)</span>\
     Overrides the location of the Nix log directory (default
     `prefix/var/log/nix`).
 
-  - [`NIX_STATE_DIR`]{#env-NIX_STATE_DIR}\
+  - <span id="env-NIX_STATE_DIR">[`NIX_STATE_DIR`](#env-NIX_STATE_DIR)</span>\
     Overrides the location of the Nix state directory (default
     `prefix/var/nix`).
 
-  - [`NIX_CONF_DIR`]{#env-NIX_CONF_DIR}\
+  - <span id="env-NIX_CONF_DIR">[`NIX_CONF_DIR`](#env-NIX_CONF_DIR)</span>\
     Overrides the location of the system Nix configuration directory
     (default `prefix/etc/nix`).
 
-  - [`NIX_CONFIG`]{#env-NIX_CONFIG}\
+  - <span id="env-NIX_CONFIG">[`NIX_CONFIG`](#env-NIX_CONFIG)</span>\
     Applies settings from Nix configuration from the environment.
     The content is treated as if it was read from a Nix configuration file.
     Settings are separated by the newline character.
 
-  - [`NIX_USER_CONF_FILES`]{#env-NIX_USER_CONF_FILES}\
+  - <span id="env-NIX_USER_CONF_FILES">[`NIX_USER_CONF_FILES`](#env-NIX_USER_CONF_FILES)</span>\
     Overrides the location of the user Nix configuration files to load
     from (defaults to the XDG spec locations). The variable is treated
     as a list separated by the `:` token.
 
-  - [`TMPDIR`]{#env-TMPDIR}\
+  - <span id="env-TMPDIR">[`TMPDIR`](#env-TMPDIR)</span>\
     Use the specified directory to store temporary files. In particular,
     this includes temporary build directories; these can take up
     substantial amounts of disk space. The default is `/tmp`.
 
-  - [`NIX_REMOTE`]{#env-NIX_REMOTE}\
+  - <span id="env-NIX_REMOTE">[`NIX_REMOTE`](#env-NIX_REMOTE)</span>\
     This variable should be set to `daemon` if you want to use the Nix
     daemon to execute Nix operations. This is necessary in [multi-user
-    Nix installations](../installation/multi-user.md). If the Nix
+    Nix installations](@docroot@/installation/multi-user.md). If the Nix
     daemon's Unix socket is at some non-standard path, this variable
     should be set to `unix://path/to/socket`. Otherwise, it should be
     left unset.
 
-  - [`NIX_SHOW_STATS`]{#env-NIX_SHOW_STATS}\
+  - <span id="env-NIX_SHOW_STATS">[`NIX_SHOW_STATS`](#env-NIX_SHOW_STATS)</span>\
     If set to `1`, Nix will print some evaluation statistics, such as
     the number of values allocated.
 
-  - [`NIX_COUNT_CALLS`]{#env-NIX_COUNT_CALLS}\
+  - <span id="env-NIX_COUNT_CALLS">[`NIX_COUNT_CALLS`](#env-NIX_COUNT_CALLS)</span>\
     If set to `1`, Nix will print how often functions were called during
     Nix expression evaluation. This is useful for profiling your Nix
     expressions.
 
-  - [`GC_INITIAL_HEAP_SIZE`]{#env-GC_INITIAL_HEAP_SIZE}\
+  - <span id="env-GC_INITIAL_HEAP_SIZE">[`GC_INITIAL_HEAP_SIZE`](#env-GC_INITIAL_HEAP_SIZE)</span>\
     If Nix has been configured to use the Boehm garbage collector, this
     variable sets the initial size of the heap in bytes. It defaults to
     384 MiB. Setting it to a low value reduces memory consumption, but
@@ -114,4 +114,4 @@ New Nix commands conform to the [XDG Base Directory Specification], and use the
 Classic Nix commands can also be made to follow this standard using the [`use-xdg-base-directories`] configuration option.
 
 [XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
-[`use-xdg-base-directories`]: ../command-ref/conf-file.md#conf-use-xdg-base-directories
\ No newline at end of file
+[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
\ No newline at end of file