doc: add a generic section on exploring package sets (#317392)

this removes the hard-coded listing from the Haskell examples, which can later be replaced by
a dynamic one as for the Python interpreters

* fix broken reference

* clarify why using `nix-env --query` makes sense

Co-authored-by: wamirez <wamirez@protonmail.com>

2 files changed, 58 insertions, 75 deletions

diff --git a/doc/languages-frameworks/haskell.section.md b/doc/languages-frameworks/haskell.section.md
index 6c2af33c8c9e..e8970b2d0335 100644
--- a/doc/languages-frameworks/haskell.section.md
+++ b/doc/languages-frameworks/haskell.section.md
@@ -21,25 +21,14 @@ Many “normal” user facing packages written in Haskell, like `niv` or `cachix
 are also exposed at the top level, and there is nothing Haskell specific to
 installing and using them.
 
-All of these packages are originally defined in the `haskellPackages` package
-set and are re-exposed with a reduced dependency closure for convenience.
-(see `justStaticExecutables` or `separateBinOutput` below)
+All of these packages are originally defined in the `haskellPackages` package set.
+The same packages are re-exposed with a reduced dependency closure for convenience (see `justStaticExecutables` or `separateBinOutput` below).
 
-The `haskellPackages` set includes at least one version of every package from
-Hackage as well as some manually injected packages. This amounts to a lot of
-packages, so it is hidden from `nix-env -qa` by default for performance reasons.
-You can still list all packages in the set like this:
+:::{.note}
+See [](#chap-language-support) for techniques to explore package sets.
+:::
 
-```console
-$ nix-env -f '<nixpkgs>' -qaP -A haskellPackages
-haskellPackages.a50                                                         a50-0.5
-haskellPackages.AAI                                                         AAI-0.2.0.1
-haskellPackages.aasam                                                       aasam-0.2.0.0
-haskellPackages.abacate                                                     abacate-0.0.0.0
-haskellPackages.abc-puzzle                                                  abc-puzzle-0.2.1
-…
-```
-Also, the `haskellPackages` set is included on [search.nixos.org].
+The `haskellPackages` set includes at least one version of every package from [Hackage](https://hackage.haskell.org/) as well as some manually injected packages.
 
 The attribute names in `haskellPackages` always correspond with their name on
 Hackage. Since Hackage allows names that are not valid Nix without escaping,
@@ -49,8 +38,7 @@ For packages that are part of [Stackage] (a curated set of known to be
 compatible packages), we use the version prescribed by a Stackage snapshot
 (usually the current LTS one) as the default version. For all other packages we
 use the latest version from [Hackage](https://hackage.org) (the repository of
-basically all open source Haskell packages). See [below](#haskell-available-
-versions) for a few more details on this.
+basically all open source Haskell packages). See [below](#haskell-available-versions) for a few more details on this.
 
 Roughly half of the 16K packages contained in `haskellPackages` don’t actually
 build and are [marked as broken semi-automatically](https://github.com/NixOS/nixpkgs/blob/haskell-updates/pkgs/development/haskell-modules/configuration-hackage2nix/broken.yaml).
@@ -63,68 +51,15 @@ How you can help with that is
 described in [Fixing a broken package](#haskell-fixing-a-broken-package).
 -->
 
-`haskellPackages` is built with our default compiler, but we also provide other
-releases of GHC and package sets built with them. You can list all available
-compilers like this:
+`haskellPackages` is built with our default compiler, but we also provide other releases of GHC and package sets built with them.
+Available compilers are collected under `haskell.compiler`.
 
-```console
-$ nix-env -f '<nixpkgs>' -qaP -A haskell.compiler
-haskell.compiler.ghc810                  ghc-8.10.7
-haskell.compiler.ghc90                   ghc-9.0.2
-haskell.compiler.ghc925                  ghc-9.2.5
-haskell.compiler.ghc926                  ghc-9.2.6
-haskell.compiler.ghc927                  ghc-9.2.7
-haskell.compiler.ghc92                   ghc-9.2.8
-haskell.compiler.ghc945                  ghc-9.4.5
-haskell.compiler.ghc946                  ghc-9.4.6
-haskell.compiler.ghc947                  ghc-9.4.7
-haskell.compiler.ghc94                   ghc-9.4.8
-haskell.compiler.ghc963                  ghc-9.6.3
-haskell.compiler.ghc96                   ghc-9.6.4
-haskell.compiler.ghc98                   ghc-9.8.1
-haskell.compiler.ghcHEAD                 ghc-9.9.20231121
-haskell.compiler.ghc8107Binary           ghc-binary-8.10.7
-haskell.compiler.ghc865Binary            ghc-binary-8.6.5
-haskell.compiler.ghc924Binary            ghc-binary-9.2.4
-haskell.compiler.integer-simple.ghc8107  ghc-integer-simple-8.10.7
-haskell.compiler.integer-simple.ghc810   ghc-integer-simple-8.10.7
-haskell.compiler.native-bignum.ghc90     ghc-native-bignum-9.0.2
-haskell.compiler.native-bignum.ghc902    ghc-native-bignum-9.0.2
-haskell.compiler.native-bignum.ghc925    ghc-native-bignum-9.2.5
-haskell.compiler.native-bignum.ghc926    ghc-native-bignum-9.2.6
-haskell.compiler.native-bignum.ghc927    ghc-native-bignum-9.2.7
-haskell.compiler.native-bignum.ghc92     ghc-native-bignum-9.2.8
-haskell.compiler.native-bignum.ghc928    ghc-native-bignum-9.2.8
-haskell.compiler.native-bignum.ghc945    ghc-native-bignum-9.4.5
-haskell.compiler.native-bignum.ghc946    ghc-native-bignum-9.4.6
-haskell.compiler.native-bignum.ghc947    ghc-native-bignum-9.4.7
-haskell.compiler.native-bignum.ghc94     ghc-native-bignum-9.4.8
-haskell.compiler.native-bignum.ghc948    ghc-native-bignum-9.4.8
-haskell.compiler.native-bignum.ghc963    ghc-native-bignum-9.6.3
-haskell.compiler.native-bignum.ghc96     ghc-native-bignum-9.6.4
-haskell.compiler.native-bignum.ghc964    ghc-native-bignum-9.6.4
-haskell.compiler.native-bignum.ghc98     ghc-native-bignum-9.8.1
-haskell.compiler.native-bignum.ghc981    ghc-native-bignum-9.8.1
-haskell.compiler.native-bignum.ghcHEAD   ghc-native-bignum-9.9.20231121
-haskell.compiler.ghcjs                   ghcjs-8.10.7
-```
-
-Each of those compiler versions has a corresponding attribute set built using
+Each of those compiler versions has a corresponding attribute set `packages` built with
 it. However, the non-standard package sets are not tested regularly and, as a
 result, contain fewer working packages. The corresponding package set for GHC
 9.4.5 is `haskell.packages.ghc945`. In fact `haskellPackages` is just an alias
 for `haskell.packages.ghc964`:
 
-```console
-$ nix-env -f '<nixpkgs>' -qaP -A haskell.packages.ghc927
-haskell.packages.ghc927.a50                                                         a50-0.5
-haskell.packages.ghc927.AAI                                                         AAI-0.2.0.1
-haskell.packages.ghc927.aasam                                                       aasam-0.2.0.0
-haskell.packages.ghc927.abacate                                                     abacate-0.0.0.0
-haskell.packages.ghc927.abc-puzzle                                                  abc-puzzle-0.2.1
-…
-```
-
 Every package set also re-exposes the GHC used to build its packages as `haskell.packages.*.ghc`.
 
 ### Available package versions {#haskell-available-versions}
diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md
index e8fee9c45216..32cb2121620b 100644
--- a/doc/languages-frameworks/index.md
+++ b/doc/languages-frameworks/index.md
@@ -2,6 +2,54 @@
 
 The [standard build environment](#chap-stdenv) makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accommodated by overriding the appropriate phases of `stdenv`. However, there are specialised functions in Nixpkgs to easily build packages for other programming languages, such as Perl or Haskell. These are described in this chapter.
 
+Each supported language or software ecosystem has its own package set named `<language or ecosystem>Packages`, which can be explored in various ways:
+
+- Search on [search.nixos.org](https://search.nixos.org/packages)
+
+  For example, search for [`haskellPackages`](https://search.nixos.org/packages?query=haskellPackages) or [`rubyPackages`](https://search.nixos.org/packages?query=rubyPackages).
+
+- Navigate attribute sets with [`nix repl`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-repl).
+
+  This technique is generally useful to inspect Nix language data structures.
+
+  :::{.example #example-navigte-nix-repl}
+
+  # Navigate Java compiler variants in `javaPackages` with `nix repl`
+
+  ```shell-session
+  $ nix repl '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable
+  nix-repl> javaPackages.<tab>
+  javaPackages.compiler               javaPackages.openjfx15              javaPackages.openjfx21              javaPackages.recurseForDerivations
+  javaPackages.jogl_2_4_0             javaPackages.openjfx17              javaPackages.openjfx22
+  javaPackages.mavenfod               javaPackages.openjfx19              javaPackages.override
+  javaPackages.openjfx11              javaPackages.openjfx20              javaPackages.overrideDerivation
+  ```
+  :::
+
+- List all derivations on the command line with [`nix-env --query`](https://nixos.org/manual/nix/stable/command-ref/nix-env/query).
+
+  `nix-env` is the only convenient way to do that, as it will skip attributes that fail [assertions](https://nixos.org/manual/nix/stable/language/constructs#assertions), such as when a package is [marked as broken](#var-meta-broken), rather than failing the entire evaluation.
+
+  :::{.example #example-list-haskellPackages}
+
+  # List all Python packages in Nixpkgs
+
+  The following command lists all [derivations names](https://nixos.org/manual/nix/stable/language/derivations#attr-name) with their attribute path from the latest Nixpkgs rolling release (`nixpkgs-unstable`).
+
+  ```shell-session
+  $ nix-env -qaP -f '<nixpkgs>' -A pythonPackages -I nixpkgs=channel:nixpkgs-unstable
+  ```
+
+  ```console
+  pythonPackages.avahi                                                  avahi-0.8
+  pythonPackages.boost                                                  boost-1.81.0
+  pythonPackages.caffe                                                  caffe-1.0
+  pythonPackages.caffeWithCuda                                          caffe-1.0
+  pythonPackages.cbeams                                                 cbeams-1.0.3
+  …
+  ```
+  :::
+
 ```{=include=} sections
 agda.section.md
 android.section.md