15 files changed, 196 insertions, 52 deletions

diff --git a/doc/build-aux/pandoc-filters/link-unix-man-references.lua b/doc/build-aux/pandoc-filters/link-unix-man-references.lua
index 12431f140fe..e437ac73a1c 100644
--- a/doc/build-aux/pandoc-filters/link-unix-man-references.lua
+++ b/doc/build-aux/pandoc-filters/link-unix-man-references.lua
@@ -1,6 +1,5 @@
 --[[
-Turns a manpage reference into a link, when a mapping is defined
-in the unix-man-urls.lua file.
+Turns a manpage reference into a link, when a mapping is defined below.
 ]]
 
 local man_urls = {
diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md
index e36724f295f..5b28b2dcb39 100644
--- a/doc/builders/fetchers.chapter.md
+++ b/doc/builders/fetchers.chapter.md
@@ -82,4 +82,11 @@ This is used with repo.or.cz repositories. The arguments expected are very simil
 
 ## `fetchFromSourcehut` {#fetchfromsourcehut}
 
-This is used with sourcehut repositories. The arguments expected are very similar to fetchFromGitHub above. Don't forget the tilde (~) in front of the user name!
+This is used with sourcehut repositories. Similar to `fetchFromGitHub` above,
+it expects `owner`, `repo`, `rev` and `sha256`, but don't forget the tilde (~)
+in front of the username! Expected arguments also include `vc` ("git" (default)
+or "hg"), `domain` and `fetchSubmodules`.
+
+If `fetchSubmodules` is `true`, `fetchFromSourcehut` uses `fetchgit`
+or `fetchhg` with `fetchSubmodules` or `fetchSubrepos` set to `true`,
+respectively. Otherwise the fetcher uses `fetchzip`.
diff --git a/doc/builders/packages/linux.section.md b/doc/builders/packages/linux.section.md
index d8f0d0ad445..f669c720710 100644
--- a/doc/builders/packages/linux.section.md
+++ b/doc/builders/packages/linux.section.md
@@ -29,7 +29,7 @@ How to add a new (major) version of the Linux kernel to Nixpkgs:
     4.  If needed you can also run `make menuconfig`:
 
         ```ShellSession
-        $ nix-env -i ncurses
+        $ nix-env -f "<nixpkgs>" -iA ncurses
         $ export NIX_CFLAGS_LINK=-lncurses
         $ make menuconfig ARCH=arch
         ```
diff --git a/doc/builders/special/mkshell.section.md b/doc/builders/special/mkshell.section.md
index 8a62c50e17d..73cc57f485b 100644
--- a/doc/builders/special/mkshell.section.md
+++ b/doc/builders/special/mkshell.section.md
@@ -1,17 +1,37 @@
 # pkgs.mkShell {#sec-pkgs-mkShell}
 
-`pkgs.mkShell` is a special kind of derivation that is only useful when using
-it combined with `nix-shell`. It will in fact fail to instantiate when invoked
-with `nix-build`.
+`pkgs.mkShell` is a specialized `stdenv.mkDerivation` that removes some
+repetition when using it with `nix-shell` (or `nix develop`).
 
 ## Usage {#sec-pkgs-mkShell-usage}
 
+Here is a common usage example:
+
 ```nix
 { pkgs ? import <nixpkgs> {} }:
 pkgs.mkShell {
-  # specify which packages to add to the shell environment
   packages = [ pkgs.gnumake ];
-  # add all the dependencies, of the given packages, to the shell environment
-  inputsFrom = with pkgs; [ hello gnutar ];
+
+  inputsFrom = [ pkgs.hello pkgs.gnutar ];
+
+  shellHook = ''
+    export DEBUG=1
+  '';
 }
 ```
+
+## Attributes
+
+* `name` (default: `nix-shell`). Set the name of the derivation.
+* `packages` (default: `[]`). Add executable packages to the `nix-shell` environment.
+* `inputsFrom` (default: `[]`). Add build dependencies of the listed derivations to the `nix-shell` environment.
+* `shellHook` (default: `""`). Bash statements that are executed by `nix-shell`.
+
+... all the attributes of `stdenv.mkDerivation`.
+
+## Building the shell
+
+This derivation output will contain a text file that contains a reference to
+all the build inputs. This is useful in CI where we want to make sure that
+every derivation, and its dependencies, build properly. Or when creating a GC
+root so that the build dependencies don't get garbage-collected.
diff --git a/doc/builders/trivial-builders.chapter.md b/doc/builders/trivial-builders.chapter.md
index c3a3572cd9f..779a0a801b4 100644
--- a/doc/builders/trivial-builders.chapter.md
+++ b/doc/builders/trivial-builders.chapter.md
@@ -47,6 +47,88 @@ These functions write `text` to the Nix store. This is useful for creating scrip
 
 Many more commands wrap `writeTextFile` including `writeText`, `writeTextDir`, `writeScript`, and `writeScriptBin`. These are convenience functions over `writeTextFile`.
 
+Here are a few examples:
+```nix
+# Writes my-file to /nix/store/<store path>
+writeTextFile {
+  name = "my-file";
+  text = ''
+    Contents of File
+  '';
+}
+# See also the `writeText` helper function below.
+
+# Writes executable my-file to /nix/store/<store path>/bin/my-file
+writeTextFile {
+  name = "my-file";
+  text = ''
+    Contents of File
+  '';
+  executable = true;
+  destination = "/bin/my-file";
+}
+# Writes contents of file to /nix/store/<store path>
+writeText "my-file"
+  ''
+  Contents of File
+  '';
+# Writes contents of file to /nix/store/<store path>/share/my-file
+writeTextDir "share/my-file"
+  ''
+  Contents of File
+  '';
+# Writes my-file to /nix/store/<store path> and makes executable
+writeScript "my-file"
+  ''
+  Contents of File
+  '';
+# Writes my-file to /nix/store/<store path>/bin/my-file and makes executable.
+writeScriptBin "my-file"
+  ''
+  Contents of File
+  '';
+# Writes my-file to /nix/store/<store path> and makes executable.
+writeShellScript "my-file"
+  ''
+  Contents of File
+  '';
+# Writes my-file to /nix/store/<store path>/bin/my-file and makes executable.
+writeShellScriptBin "my-file"
+  ''
+  Contents of File
+  '';
+
+```
+
+## `concatTextFile`, `concatText`, `concatScript` {#trivial-builder-concatText}
+
+These functions concatenate `files` to the Nix store in a single file. This is useful for configuration files structured in lines of text. `concatTextFile` takes an attribute set and expects two arguments, `name` and `files`. `name` corresponds to the name used in the Nix store path. `files` will be the files to be concatenated. You can also set `executable` to true to make this file have the executable bit set.
+`concatText` and`concatScript` are simple wrappers over `concatTextFile`.
+
+Here are a few examples:
+```nix
+
+# Writes my-file to /nix/store/<store path>
+concatTextFile {
+  name = "my-file";
+  files = [ drv1 "${drv2}/path/to/file" ];
+}
+# See also the `concatText` helper function below.
+
+# Writes executable my-file to /nix/store/<store path>/bin/my-file
+concatTextFile {
+  name = "my-file";
+  files = [ drv1 "${drv2}/path/to/file" ];
+  executable = true;
+  destination = "/bin/my-file";
+}
+# Writes contents of files to /nix/store/<store path>
+concatText "my-file" [ file1 file2 ]
+
+# Writes contents of files to /nix/store/<store path>
+concatScript "my-file" [ file1 file2 ]
+```
+
 ## `writeShellApplication` {#trivial-builder-writeShellApplication}
 
 This can be used to easily produce a shell script that has some dependencies (`runtimeInputs`). It automatically sets the `PATH` of the script to contain all of the listed inputs, sets some sanity shellopts (`errexit`, `nounset`, `pipefail`), and checks the resulting script with [`shellcheck`](https://github.com/koalaman/shellcheck).
@@ -72,6 +154,26 @@ validation.
 ## `symlinkJoin` {#trivial-builder-symlinkJoin}
 
 This can be used to put many derivations into the same directory structure. It works by creating a new derivation and adding symlinks to each of the paths listed. It expects two arguments, `name`, and `paths`. `name` is the name used in the Nix store path for the created derivation. `paths` is a list of paths that will be symlinked. These paths can be to Nix store derivations or any other subdirectory contained within.
+Here is an example:
+```nix
+# adds symlinks of hello and stack to current build and prints "links added"
+symlinkJoin { name = "myexample"; paths = [ pkgs.hello pkgs.stack ]; postBuild = "echo links added"; }
+```
+This creates a derivation with a directory structure like the following:
+```
+/nix/store/sglsr5g079a5235hy29da3mq3hv8sjmm-myexample
+|-- bin
+|   |-- hello -> /nix/store/qy93dp4a3rqyn2mz63fbxjg228hffwyw-hello-2.10/bin/hello
+|   `-- stack -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/bin/stack
+`-- share
+    |-- bash-completion
+    |   `-- completions
+    |       `-- stack -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/share/bash-completion/completions/stack
+    |-- fish
+    |   `-- vendor_completions.d
+    |       `-- stack.fish -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/share/fish/vendor_completions.d/stack.fish
+...
+```
 
 ## `writeReferencesToFile` {#trivial-builder-writeReferencesToFile}
 
diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md
index 178fdb36262..1384772ebb2 100644
--- a/doc/contributing/contributing-to-documentation.chapter.md
+++ b/doc/contributing/contributing-to-documentation.chapter.md
@@ -55,7 +55,7 @@ Additionally, the following syntax extensions are currently used:
 - []{#ssec-contributing-markup-inline-roles}
   If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`.
 
-  The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/unix-man-urls.lua`.
+  The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/link-unix-man-references.lua`.
 
   This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax.
 
diff --git a/doc/contributing/submitting-changes.chapter.md b/doc/contributing/submitting-changes.chapter.md
index 221ba300619..09ffba3dc6f 100644
--- a/doc/contributing/submitting-changes.chapter.md
+++ b/doc/contributing/submitting-changes.chapter.md
@@ -43,13 +43,13 @@
   - nixpkgs:
 
     - update pkg
-      - `nix-env -i pkg-name -f <path to your local nixpkgs folder>`
+      - `nix-env -iA pkg-attribute-name -f <path to your local nixpkgs folder>`
     - add pkg
       - Make sure it’s in `pkgs/top-level/all-packages.nix`
-      - `nix-env -i pkg-name -f <path to your local nixpkgs folder>`
+      - `nix-env -iA pkg-attribute-name -f <path to your local nixpkgs folder>`
     - _If you don’t want to install pkg in you profile_.
-      - `nix-build -A pkg-attribute-name <path to your local nixpkgs folder>/default.nix` and check results in the folder `result`. It will appear in the same directory where you did `nix-build`.
-    - If you did `nix-env -i pkg-name` you can do `nix-env -e pkg-name` to uninstall it from your system.
+      - `nix-build -A pkg-attribute-name <path to your local nixpkgs folder>` and check results in the folder `result`. It will appear in the same directory where you did `nix-build`.
+    - If you installed your package with `nix-env`, you can run `nix-env -e pkg-name` where `pkg-name` is as reported by `nix-env -q` to uninstall it from your system.
 
   - NixOS and its modules:
     - You can add new module to your NixOS configuration file (usually it’s `/etc/nixos/configuration.nix`). And do `sudo nixos-rebuild test -I nixpkgs=<path to your local nixpkgs folder> --fast`.
@@ -246,11 +246,21 @@ If the branch is already in a broken state, please refrain from adding extra new
 
 ### Stable release branches {#submitting-changes-stable-release-branches}
 
-For cherry-picking a commit to a stable release branch (“backporting”), use `git cherry-pick -x <original commit>` so that the original commit id is included in the commit.
+The same staging workflow applies to stable release branches, but the main branch is called `release-*` instead of `master`.
 
-Add a reason for the backport by using `git cherry-pick -xe <original commit>` instead when it is not obvious from the original commit message. It is not needed when it's a minor version update that includes security and bug fixes but don't add new features or when the commit fixes an otherwise broken package.
+Example branch names: `release-21.11`, `staging-21.11`, `staging-next-21.11`.
 
-For backporting Pull Requests to stable branches, assign label `backport <branch>` to the original Pull Requests and automation should take care of the rest once the Pull Requests is merged.
+Most changes added to the stable release branches are cherry-picked (“backported”) from the `master` and staging branches.
+
+#### Automatically backporting a Pull Request {#submitting-changes-stable-release-branches-automatic-backports}
+
+Assign label `backport <branch>` (e.g. `backport release-21.11`) to the PR and a backport PR is automatically created after the PR is merged.
+
+#### Manually backporting changes {#submitting-changes-stable-release-branches-manual-backports}
+
+Cherry-pick changes via `git cherry-pick -x <original commit>` so that the original commit id is included in the commit message.
+
+Add a reason for the backport when it is not obvious from the original commit message. You can do this by cherry picking with `git cherry-pick -xe <original commit>`, which allows editing the commit message. This is not needed for minor version updates that include security and bug fixes but don't add new features or when the commit fixes an otherwise broken package.
 
 Here is an example of a cherry-picked commit message with good reason description:
 
diff --git a/doc/languages-frameworks/beam.section.md b/doc/languages-frameworks/beam.section.md
index 9b09d0329c5..f6c74cb01e4 100644
--- a/doc/languages-frameworks/beam.section.md
+++ b/doc/languages-frameworks/beam.section.md
@@ -74,7 +74,7 @@ there are 3 steps, frontend dependencies (javascript), backend dependencies (eli
 
 ##### mixRelease - Frontend dependencies (javascript) {#mix-release-javascript-deps}
 
-for phoenix projects, inside of nixpkgs you can either use yarn2nix (mkYarnModule) or node2nix. An example with yarn2nix can be found [here](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/web-apps/plausible/default.nix#L39). An example with node2nix will follow. To package something outside of nixpkgs, you have alternatives like [npmlock2nix](https://github.com/nix-community/npmlock2nix) or [nix-npm-buildpackage](https://github.com/serokell/nix-npm-buildpackage)
+For phoenix projects, inside of nixpkgs you can either use yarn2nix (mkYarnModule) or node2nix. An example with yarn2nix can be found [here](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/web-apps/plausible/default.nix#L39). An example with node2nix will follow. To package something outside of nixpkgs, you have alternatives like [npmlock2nix](https://github.com/nix-community/npmlock2nix) or [nix-npm-buildpackage](https://github.com/serokell/nix-npm-buildpackage)
 
 ##### mixRelease - backend dependencies (mix) {#mix-release-mix-deps}
 
@@ -82,13 +82,13 @@ There are 2 ways to package backend dependencies. With mix2nix and with a fixed-
 
 ###### mix2nix {#mix2nix}
 
-mix2nix is a cli tool available in nixpkgs. it will generate a nix expression from a mix.lock file. It is quite standard in the 2nix tool series.
+`mix2nix` is a cli tool available in nixpkgs. it will generate a nix expression from a mix.lock file. It is quite standard in the 2nix tool series.
 
 Note that currently mix2nix can't handle git dependencies inside the mix.lock file. If you have git dependencies, you can either add them manually (see [example](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/pleroma/default.nix#L20)) or use the FOD method.
 
 The advantage of using mix2nix is that nix will know your whole dependency graph. On a dependency update, this won't trigger a full rebuild and download of all the dependencies, where FOD will do so.
 
-practical steps:
+Practical steps:
 
 - run `mix2nix > mix_deps.nix` in the upstream repo.
 - pass `mixNixDeps = with pkgs; import ./mix_deps.nix { inherit lib beamPackages; };` as an argument to mixRelease.
@@ -280,6 +280,30 @@ mkShell {
 }
 ```
 
+### Using an overlay
+
+If you need to use an overlay to change some attributes of a derivation, e.g. if you need a bugfix from a version that is not yet available in nixpkgs, you can override attributes such as `version` (and the corresponding `sha256`) and then use this overlay in your development environment:
+
+#### `shell.nix`
+
+```nix
+let
+  elixir_1_13_1_overlay = (self: super: {
+      elixir_1_13 = super.elixir_1_13.override {
+        version = "1.13.1";
+        sha256 = "0z0b1w2vvw4vsnb99779c2jgn9bgslg7b1pmd9vlbv02nza9qj5p";
+      };
+    });
+  pkgs = import <nixpkgs> { overlays = [ elixir_1_13_1_overlay ]; };
+in
+with pkgs;
+mkShell {
+  buildInputs = [
+    elixir_1_13
+  ];
+}
+```
+
 #### Elixir - Phoenix project {#elixir---phoenix-project}
 
 Here is an example `shell.nix`.
diff --git a/doc/languages-frameworks/dotnet.section.md b/doc/languages-frameworks/dotnet.section.md
index 159347008e8..88e1a0b2959 100644
--- a/doc/languages-frameworks/dotnet.section.md
+++ b/doc/languages-frameworks/dotnet.section.md
@@ -90,7 +90,7 @@ To package Dotnet applications, you can use `buildDotnetModule`. This has simila
 * `dotnet-sdk` is useful in cases where you need to change what dotnet SDK is being used.
 * `dotnet-runtime` is useful in cases where you need to change what dotnet runtime is being used. This can be either a regular dotnet runtime, or an aspnetcore.
 * `dotnet-test-sdk` is useful in cases where unit tests expect a different dotnet SDK. By default, this is set to the `dotnet-sdk` attribute.
-* `testProjectFile` is useful in cases where the regular project file does not contain the unit tests. By default, this is set to the `projectFile` attribute.
+* `testProjectFile` is useful in cases where the regular project file does not contain the unit tests. It gets restored and build, but not installed. You may need to regenerate your nuget lockfile after setting this.
 * `disabledTests` is used to disable running specific unit tests. This gets passed as: `dotnet test --filter "FullyQualifiedName!={}"`, to ensure compatibility with all unit test frameworks.
 * `dotnetRestoreFlags` can be used to pass flags to `dotnet restore`.
 * `dotnetBuildFlags` can be used to pass flags to `dotnet build`.
diff --git a/doc/languages-frameworks/emscripten.section.md b/doc/languages-frameworks/emscripten.section.md
index b3ddf0cedae..c96f689c4c0 100644
--- a/doc/languages-frameworks/emscripten.section.md
+++ b/doc/languages-frameworks/emscripten.section.md
@@ -15,12 +15,12 @@ Modes of use of `emscripten`:
 
    If you want to work with `emcc`, `emconfigure` and `emmake` as you are used to from Ubuntu and similar distributions you can use these commands:
 
-    * `nix-env -i emscripten`
+    * `nix-env -f "<nixpkgs>" -iA emscripten`
     * `nix-shell -p emscripten`
 
 * **Declarative usage**:
 
-    This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`.
+    This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`. From the root of the nixpkgs repository:
     * build and install all packages:
         * `nix-env -iA emscriptenPackages`
 
diff --git a/doc/languages-frameworks/go.section.md b/doc/languages-frameworks/go.section.md
index 45d85f1f99e..411205d08e4 100644
--- a/doc/languages-frameworks/go.section.md
+++ b/doc/languages-frameworks/go.section.md
@@ -12,8 +12,7 @@ The function `buildGoModule` builds Go programs managed with Go modules. It buil
 In the following is an example expression using `buildGoModule`, the following arguments are of special significance to the function:
 
 - `vendorSha256`: is the hash of the output of the intermediate fetcher derivation. `vendorSha256` can also take `null` as an input. When `null` is used as a value, rather than fetching the dependencies and vendoring them, we use the vendoring included within the source repo. If you'd like to not have to update this field on dependency changes, run `go mod vendor` in your source repo and set `vendorSha256 = null;`
-- `runVend`: runs the vend command to generate the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build.
-- `proxyVendor`: Fetches (go mod download) and proxies the vendor directory. This is useful if any dependency has case-insensitive conflicts which will produce platform dependant `vendorSha256` checksums.
+- `proxyVendor`: Fetches (go mod download) and proxies the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build or if any dependency has case-insensitive conflicts which will produce platform dependant `vendorSha256` checksums.
 
 ```nix
 pet = buildGoModule rec {
@@ -29,14 +28,11 @@ pet = buildGoModule rec {
 
   vendorSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j";
 
-  runVend = true;
-
   meta = with lib; {
     description = "Simple command-line snippet manager, written in Go";
     homepage = "https://github.com/knqyf263/pet";
     license = licenses.mit;
     maintainers = with maintainers; [ kalbasit ];
-    platforms = platforms.linux ++ platforms.darwin;
   };
 }
 ```
diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md
index ffdd706eb0b..19146844cff 100644
--- a/doc/languages-frameworks/idris.section.md
+++ b/doc/languages-frameworks/idris.section.md
@@ -5,10 +5,7 @@
 The easiest way to get a working idris version is to install the `idris` attribute:
 
 ```ShellSession
-$ # On NixOS
-$ nix-env -i nixos.idris
-$ # On non-NixOS
-$ nix-env -i nixpkgs.idris
+$ nix-env -f "<nixpkgs>" -iA idris
 ```
 
 This however only provides the `prelude` and `base` libraries. To install idris with additional libraries, you can use the `idrisPackages.with-packages` function, e.g. in an overlay in `~/.config/nixpkgs/overlays/my-idris.nix`:
diff --git a/doc/languages-frameworks/octave.section.md b/doc/languages-frameworks/octave.section.md
index ff872f4a755..4ad2cb0d5fb 100644
--- a/doc/languages-frameworks/octave.section.md
+++ b/doc/languages-frameworks/octave.section.md
@@ -24,18 +24,10 @@ You can test building an Octave package as follows:
 $ nix-build -A octavePackages.symbolic
 ```
 
-When building Octave packages with `nix-build`, the `buildOctavePackage` function adds `octave-octaveVersion` to; the start of the package's name attribute.
-
-This can be required when installing the package using `nix-env`:
-
-```ShellSession
-$ nix-env -i octave-6.2.0-symbolic
-```
-
-Although, you can also install it using the attribute name:
+To install it into your user profile, run this command from the root of the repository:
 
 ```ShellSession
-$ nix-env -i -A octavePackages.symbolic
+$ nix-env -f. -iA octavePackages.symbolic
 ```
 
 You can build Octave with packages by using the `withPackages` passed-through function.
diff --git a/doc/languages-frameworks/perl.section.md b/doc/languages-frameworks/perl.section.md
index c992b9d658b..9bfd209fec5 100644
--- a/doc/languages-frameworks/perl.section.md
+++ b/doc/languages-frameworks/perl.section.md
@@ -58,13 +58,7 @@ in `all-packages.nix`. You can test building a Perl package as follows:
 $ nix-build -A perlPackages.ClassC3
 ```
 
-`buildPerlPackage` adds `perl-` to the start of the name attribute, so the package above is actually called `perl-Class-C3-0.21`. So to install it, you can say:
-
-```ShellSession
-$ nix-env -i perl-Class-C3
-```
-
-(Of course you can also install using the attribute name: `nix-env -i -A perlPackages.ClassC3`.)
+To install it with `nix-env` instead: `nix-env -f. -iA perlPackages.ClassC3`.
 
 So what does `buildPerlPackage` do? It does the following:
 
@@ -135,9 +129,11 @@ This will remove the `-I` flags from the shebang line, rewrite them in the `use
 Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program `nix-generate-from-cpan`, which can be installed as follows:
 
 ```ShellSession
-$ nix-env -i nix-generate-from-cpan
+$ nix-env -f "<nixpkgs>" -iA nix-generate-from-cpan
 ```
 
+Substitute `<nixpkgs>` by the path of a nixpkgs clone to use the latest version.
+
 This program takes a Perl module name, looks it up on CPAN, fetches and unpacks the corresponding package, and prints a Nix expression on standard output. For example:
 
 ```ShellSession
diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md
index 4d70409a20c..9f9ace513c3 100644
--- a/doc/languages-frameworks/python.section.md
+++ b/doc/languages-frameworks/python.section.md
@@ -764,7 +764,7 @@ and in this case the `python38` interpreter is automatically used.
 
 ### Interpreters {#interpreters}
 
-Versions 2.7, 3.6, 3.7, 3.8 and 3.9 of the CPython interpreter are available as
+Versions 2.7, 3.7, 3.8 and 3.9 of the CPython interpreter are available as
 respectively `python27`, `python37`, `python38` and `python39`. The
 aliases `python2` and `python3` correspond to respectively `python27` and
 `python39`. The attribute `python` maps to `python2`. The PyPy interpreters
@@ -834,6 +834,7 @@ sets are
 * `pkgs.python38Packages`
 * `pkgs.python39Packages`
 * `pkgs.python310Packages`
+* `pkgs.python311Packages`
 * `pkgs.pypyPackages`
 
 and the aliases