From be7c236565ae981a5b0f5a952bfb8380418cea41 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 26 Apr 2023 15:37:08 +0200
Subject: [PATCH] move compatibility info to `nix profile` docs

---
 .../src/command-ref/files/user-profiles.md    | 25 ---------------
 src/nix/profile.md                            | 32 +++++++++++++++++++
 2 files changed, 32 insertions(+), 25 deletions(-)

diff --git a/doc/manual/src/command-ref/files/user-profiles.md b/doc/manual/src/command-ref/files/user-profiles.md
index 4296d473c..1862caff8 100644
--- a/doc/manual/src/command-ref/files/user-profiles.md
+++ b/doc/manual/src/command-ref/files/user-profiles.md
@@ -7,31 +7,6 @@ A directory that contains links to user profiles managed by [`nix-env`] and [`ni
 
 A profile is a directory of symlinks to files in the Nix store.
 
-### Profile compatibility
-
-> **Warning**
->
-> `nix profile` is experimental.
-> Once you have used `nix profile` you can no longer use `nix-env` without first deleting `$XDG_STATE_HOME/nix/profiles/profile`
-
-Once you installed a package with `nix profile`, you get the following error message when using `nix-env`:
-
-```console
-$ nix-env -f '<nixpkgs>' -iA 'hello'
-error: --- Error ----------------------------------------------------------------------------------------------------------------- nix-env
-profile '/home/alice/.local/state/nix/profiles/profile' is incompatible with 'nix-env'; please use 'nix profile' instead
-```
-
-To migrate back to `nix-env` you can delete your current profile:
-
-> **Warning**
->
-> This will delete packages that have been installed before, so you may want to back up this information before running the command.
-
-```console
- $ rm -rf "${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/profile"
-```
-
 ### Filesystem layout
 
 Profiles are versioned as follows. When using a profile named *path*, *path* is a symlink to *path*`-`*N*`-link`, where *N* is the version of the profile.
diff --git a/src/nix/profile.md b/src/nix/profile.md
index 1c4e92ee4..ddbb1ba36 100644
--- a/src/nix/profile.md
+++ b/src/nix/profile.md
@@ -10,4 +10,36 @@ them to be rolled back easily.
 # Files
 
 )""
+
 #include "doc/files/user-profiles.md"
+
+R""(
+
+### Profile compatibility
+
+> **Warning**
+>
+> Once you have used [`nix profile`] you can no longer use [`nix-env`] without first deleting `$XDG_STATE_HOME/nix/profiles/profile`
+
+[`nix-env`]: @docroot@/command-ref/nix-env.md
+[`nix profile`]: @docroot@/command-ref/new-cli/nix3-profile.md
+
+Once you installed a package with [`nix profile`], you get the following error message when using [`nix-env`]:
+
+```console
+$ nix-env -f '<nixpkgs>' -iA 'hello'
+error: nix-env
+profile '/home/alice/.local/state/nix/profiles/profile' is incompatible with 'nix-env'; please use 'nix profile' instead
+```
+
+To migrate back to `nix-env` you can delete your current profile:
+
+> **Warning**
+>
+> This will delete packages that have been installed before, so you may want to back up this information before running the command.
+
+```console
+ $ rm -rf "${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/profile"
+```
+
+)""