From 38d9d536a884db28edb4f31a415921029c93faae Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 5 Sep 2024 03:28:06 +0200
Subject: [PATCH] docs: small fixups on the default expression

- highlighted example
- linked definitions to the glossary (this is a shorter read)
- fixed some artefact
---
 .../files/default-nix-expression.md           | 30 ++++++++++---------
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/doc/manual/src/command-ref/files/default-nix-expression.md b/doc/manual/src/command-ref/files/default-nix-expression.md
index 620f7035c..2bd45ff5d 100644
--- a/doc/manual/src/command-ref/files/default-nix-expression.md
+++ b/doc/manual/src/command-ref/files/default-nix-expression.md
@@ -1,6 +1,6 @@
 ## Default Nix expression
 
-The source for the default [Nix expressions](@docroot@/language/index.md) used by [`nix-env`]:
+The source for the [Nix expressions](@docroot@/glossary.md#gloss-nix-expression) used by [`nix-env`] by default:
 
 - `~/.nix-defexpr`
 - `$XDG_STATE_HOME/nix/defexpr` if [`use-xdg-base-directories`] is set to `true`.
@@ -18,24 +18,25 @@ Then, the resulting expression is interpreted like this:
 - If the expression is an attribute set, it is used as the default Nix expression.
 - If the expression is a function, an empty set is passed as argument and the return value is used as the default Nix expression.
 
-
-For example, if the default expression contains two files, `foo.nix` and `bar.nix`, then the default Nix expression will be equivalent to
-
-```nix
-{
-  foo = import ~/.nix-defexpr/foo.nix;
-  bar = import ~/.nix-defexpr/bar.nix;
-}
-```
+> **Example**
+>
+> If the default expression contains two files, `foo.nix` and `bar.nix`, then the default Nix expression will be equivalent to
+>
+> ```nix
+> {
+>   foo = import ~/.nix-defexpr/foo.nix;
+>   bar = import ~/.nix-defexpr/bar.nix;
+> }
+> ```
 
 The file [`manifest.nix`](@docroot@/command-ref/files/manifest.nix.md) is always ignored.
 
-The command [`nix-channel`] places a symlink to the user's current [channels profile](@docroot@/command-ref/files/channels.md) in this directory.
+The command [`nix-channel`] places a symlink to the current user's [channels] in this directory, the [user channel link](#user-channel-link).
 This makes all subscribed channels available as attributes in the default expression.
 
 ## User channel link
 
-A symlink that ensures that [`nix-env`] can find your channels:
+A symlink that ensures that [`nix-env`] can find the current user's [channels]:
 
 - `~/.nix-defexpr/channels`
 - `$XDG_STATE_HOME/defexpr/channels` if [`use-xdg-base-directories`] is set to `true`.
@@ -45,8 +46,9 @@ This symlink points to:
 - `$XDG_STATE_HOME/profiles/channels` for regular users
 - `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root`
 
-In a multi-user installation, you may also have `~/.nix-defexpr/channels_root`, which links to the channels of the root user.[`nix-env`]: ../nix-env.md
+In a multi-user installation, you may also have `~/.nix-defexpr/channels_root`, which links to the channels of the root user.
 
-[`nix-env`]: @docroot@/command-ref/nix-env.md
 [`nix-channel`]: @docroot@/command-ref/nix-channel.md
+[`nix-env`]: @docroot@/command-ref/nix-env.md
 [`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
+[channels]: @docroot@/command-ref/files/channels.md