add HTML anchors for options and environment variables

[fricklerhandwerk]

this is due to lowdown not supporting the non-standard syntax,
same as in b8a1ff9

Motivation

fix manual rendering issues on the terminal

Checklist for maintainers

Maintainers: tick if completed or explain if not relevant

• agreed on idea
• agreed on implementation strategy
• tests, as appropriate
  • functional tests - tests/**.sh
  • unit tests - src/*/tests
  • integration tests - tests/nixos/*
• documentation in the manual
• code and comments are self-explanatory
• commit message explains why the change was made
• new feature or incompatible change: updated release notes

Priorities

Add 👍 to pull requests you find important.

[edolstra]

For maintainability, it seems better to fix lowdown than to add all these duplicate anchors everywhere. Furthermore, the lowdown text renderer doesn't parse <span> at all, so you get output like

    · <span id="env-IN_NIX_SHELL">IN_NIX_SHELL</span> 

[fricklerhandwerk]

the lowdown text renderer doesn't parse <span> at all

Wait, but why does b8a1ff9 work then?

fix lowdown

I agree, but... ew. Also, who's gonna do it?

[edolstra]

Wait, but why does b8a1ff9 work then?

It doesn't for me... That's why I have that useAnchors stuff in #8084. How do these spans get rendered in nix help output for you?

[fricklerhandwerk]

This PR is a split-out of #7518, because it's a somewhat unrelated change. Built on top of that branch it looks like this (and works for man and the new nix-store --realise --help):

Common Environment Variables
       Most Nix commands interpret the following environment variables:

       • IN_NIX_SHELL
         Indicator that tells if the current environment was set up by nix-shell. It can have the values pure or impure.

       • NIX_PATH
         A colon-separated list  of  directories  used  to  look  up  the  location  of  Nix  expressions  using  paths  enclosed  in  angle  brackets  (i.e.,  <path>),  e.g.
         /home/eelco/Dev:/etc/nixos. It can be extended using the -I option.

         If NIX_PATH is not set at all, Nix will fall back to the following list in impure and unrestricted evaluation mode:

         1.     $HOME/.nix-defexpr/channels
         2.     nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixpkgs
         3.     /nix/var/nix/profiles/per-user/root/channels

         If NIX_PATH is set to an empty string, resolving search paths will always fail.  For example, attempting to use <nixpkgs> will produce:

       error: file 'nixpkgs' was not found in the Nix search path

       • NIX_IGNORE_SYMLINK_STORE
         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 resolving all symlink components. Thus, builds on different machines (with /nix/store resolving to different locations) could yield different
         results. This is generally not a problem, except when builds are deployed to machines where /nix/store resolves differently. If you are sure that you’re not going to
         do that, you can set NIX_IGNORE_SYMLINK_STORE to 1.

         Note that if you’re symlinking the Nix store so that you can put it on another file system than the root file system, on Linux you’re better  off  using  bind  mount
         points, e.g.,

Note the rendering error for what's an indented code block, which I didn't notice on the old PR I merged yesterday because the environment variables overview does not live in the man pages yet. Will fix that forward...

[edolstra]

I guess that's the man output, which is a different renderer than the text output.

[balsoft]

@edolstra

Here's what it looks like from me, running nix-store --realise --help:

Common Environment Variables
       Most Nix commands interpret the following environment variables:

       • IN_NIX_SHELL
         Indicator that tells if the current environment was set up by nix-shell. It can have the values pure or impure.

       • NIX_PATH
         A  colon-separated  list  of  directories  used  to look up the location of Nix expressions using paths enclosed in angle brackets
         (i.e., <path>), e.g. /home/eelco/Dev:/etc/nixos. It can be extended using the -I option.

         If NIX_PATH is not set at all, Nix will fall back to the following list in impure and unrestricted evaluation mode:

         1.     $HOME/.nix-defexpr/channels
         2.     nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixpkgs
         3.     /nix/var/nix/profiles/per-user/root/channels

         If NIX_PATH is set to an empty string, resolving search paths will always fail.  For example, attempting  to  use  <nixpkgs>  will
         produce:

       error: file 'nixpkgs' was not found in the Nix search path

This is the corresponding markdown source (I'm running this on doc-commands branch):

# Common Environment Variables

Most Nix commands interpret the following environment variables:

  - <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`.

  - <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](@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](@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](@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`
      3. `/nix/var/nix/profiles/per-user/root/channels`

    If `NIX_PATH` is set to an empty string, resolving search paths will always fail.
    For example, attempting to use `<nixpkgs>` will produce:

        error: file 'nixpkgs' was not found in the Nix search path

[fricklerhandwerk]

@edolstra since @roberth reviewed #7518 and it worked for him too, what do we do now? I think this is mergeable.

[fricklerhandwerk]

There was no diff left after previous changes.