this adds support for structural includes to nixos-render-docs.
structural includes provide a way to denote the (sub)structure of the
nixos manual in the markdown source files, very similar to how we used
literal docbook blocks before, and are processed by nixos-render-docs
without involvement of xml tooling. this will ultimately allow us to
emit the nixos manual in other formats as well, e.g. html, without going
through docbook at all.
alternatives to this source layout were also considered:
a parallel structure using e.g. toml files that describe the document
tree and links to each part is possible, but much more complicated to
implement than the solution chosen here and makes it harder to follow
which files have what substructure. it also makes it much harder to
include a substructure in the middle of a file.
much the same goes for command-line arguments to the converter, only
that command-lined arguments are even harder to specify correctly and
cannot be reasonably pulled together from many places without involving
another layer of tooling. cli arguments would also mean that the manual
structure would be fixed in default.nix, which is also not ideal.
We need to move NixOS containers somewhere else so these don't clash
with Podman, Skopeo & other container software in the libpod &
cri-o/cri-u/libcontainer ecosystems.
The state directory move is not strictly a requirement but is good for
consistency.
the `nixos-rebuild` command has multiple subcommands, and not each of
them would fix the problem of a large `/boot` partition, so let’s be
more precise here.
Divide the "Service Management" chapter into two sections. The 1st (the
original) explaining General, not NixOS specific ways to interact with
Systemd. The 2nd section, explaining NixOS specific things worth
knowing.
Explain in the 2nd section a bit NixOS modules and services of Nixpkgs,
and mention `systemd.user.services` option. Give an example
demonstrating how to enable imperatively an upstream provided unit file
for a user. Explain why `systemctl --user enable` doesn't work for the
long term on NixOS.
I have a nixops network where I deploy containers using the `container`
backend which uses `nixos-container` intenrally to deploy several
containers to a certain host.
During that time I removed and added new containers and while trying to
deploy those to a different host I realized that it isn't guaranteed
that each container gets the same IP address which is a problem as some
parts of the deployment need to know which container is using which IP
(i.e. to configure port forwarding on the host).
With this change you can specify the container's IP like this (and don't
have to use the arbitrarily used 10.233.0.0/16 subnet):
```
$ nixos-container create test --config-file test-container.nix \
--local-address 10.235.1.2 --host-address 10.235.1.1
```
Nix commands inside the container have been broken since 18.03,
and no fix is yet in sight. Lets remove from the documentation
that this is a usecase that we support, as it doesn't seem
likely that this will be fixed before 18.09 either.
See #40355
