From 32f75a0f2af55b50061629fd4e51221f15ada457 Mon Sep 17 00:00:00 2001 From: Doron Behar Date: Sat, 12 Aug 2023 13:13:14 +0300 Subject: nixos/install-tools: Add manpages to packages instead of seperating them Since each such `nixos-*` tool has it's own derivation, exposed in pkgs, There is no point in separating the manuals from the packages. If someone wishes to have the tools without the manuals, they can use meta.outputsToInstall to disable the installation of the manpages of these packages. This Fixes #244450. --- nixos/modules/installer/tools/manpages/README.md | 57 ++++++ .../installer/tools/manpages/nixos-build-vms.8 | 105 +++++++++++ .../modules/installer/tools/manpages/nixos-enter.8 | 72 ++++++++ .../tools/manpages/nixos-generate-config.8 | 165 ++++++++++++++++++ .../installer/tools/manpages/nixos-install.8 | 191 +++++++++++++++++++++ .../installer/tools/manpages/nixos-version.8 | 86 ++++++++++ nixos/modules/installer/tools/tools.nix | 11 ++ 7 files changed, 687 insertions(+) create mode 100644 nixos/modules/installer/tools/manpages/README.md create mode 100644 nixos/modules/installer/tools/manpages/nixos-build-vms.8 create mode 100644 nixos/modules/installer/tools/manpages/nixos-enter.8 create mode 100644 nixos/modules/installer/tools/manpages/nixos-generate-config.8 create mode 100644 nixos/modules/installer/tools/manpages/nixos-install.8 create mode 100644 nixos/modules/installer/tools/manpages/nixos-version.8 (limited to 'nixos/modules/installer/tools') diff --git a/nixos/modules/installer/tools/manpages/README.md b/nixos/modules/installer/tools/manpages/README.md new file mode 100644 index 00000000000..05cb83902c7 --- /dev/null +++ b/nixos/modules/installer/tools/manpages/README.md @@ -0,0 +1,57 @@ +# NixOS manpages + +This is the collection of NixOS manpages, excluding `configuration.nix(5)`. + +Man pages are written in [`mdoc(7)` format](https://mandoc.bsd.lv/man/mdoc.7.html) and should be portable between mandoc and groff for rendering (though minor differences may occur, mandoc and groff seem to have slightly different spacing rules.) + +For previewing edited files, you can just run `man -l path/to/file.8` and you will see it rendered. + +Being written in `mdoc` these manpages use semantic markup. This file provides a guideline on where to apply which of the semantic elements of `mdoc`. + +### Command lines and arguments + +In any manpage, commands, flags and arguments to the *current* executable should be marked according to their semantics. Commands, flags and arguments passed to *other* executables should not be marked like this and should instead be considered as code examples and marked with `Ql`. + + - Use `Fl` to mark flag arguments, `Ar` for their arguments. + - Repeating arguments should be marked by adding ellipses (`...`). + - Use `Cm` to mark literal string arguments, e.g. the `boot` command argument passed to `nixos-rebuild`. + - Optional flags or arguments should be marked with `Op`. This includes optional repeating arguments. + - Required flags or arguments should not be marked. + - Mutually exclusive groups of arguments should be enclosed in curly brackets, preferably created with `Bro`/`Brc` blocks. + +When an argument is used in an example it should be marked up with `Ar` again to differentiate it from a constant. For example, a command with a `--host name` flag that calls ssh to retrieve the host's local time would signify this thusly: +``` +This will run +.Ic ssh Ar name Ic time +to retrieve the remote time. +``` + +### Paths, NixOS options, environment variables + +Constant paths should be marked with `Pa`, NixOS options with `Va`, and environment variables with `Ev`. + +Generated paths, e.g. `result/bin/run-hostname-vm` (where `hostname` is a variable or arguments) should be marked as `Ql` inline literals with their variable components marked appropriately. + + - Taking `hostname` from an argument become `.Ql result/bin/run- Ns Ar hostname Ns -vm` + - Taking `hostname` from a variable otherwise defined becomes `.Ql result/bin/run- Ns Va hostname Ns -vm` + +### Code examples and other commands + +In free text names and complete invocations of other commands (e.g. `ssh` or `tar -xvf src.tar`) should be marked with `Ic`, fragments of command lines should be marked with `Ql`. + +Larger code blocks or those that cannot be shown inline should use indented literal display block markup for their contents, i.e. +``` +.Bd -literal -offset indent +... +.Ed +``` +Contents of code blocks may be marked up further, e.g. if they refer to arguments that will be substituted into them: +``` +.Bd -literal -offset indent +{ + options.hostname = "\c +.Ar hostname Ns \c +"; +} +.Ed +``` diff --git a/nixos/modules/installer/tools/manpages/nixos-build-vms.8 b/nixos/modules/installer/tools/manpages/nixos-build-vms.8 new file mode 100644 index 00000000000..6a8f2c42edd --- /dev/null +++ b/nixos/modules/installer/tools/manpages/nixos-build-vms.8 @@ -0,0 +1,105 @@ +.Dd January 1, 1980 +.Dt nixos-build-vms 8 +.Os +.Sh NAME +.Nm nixos-build-vms +.Nd build a network of virtual machines from a network of NixOS configurations +. +. +. +.Sh SYNOPSIS +.Nm nixos-build-vms +.Op Fl -show-trace +.Op Fl -no-out-link +.Op Fl -help +.Op Fl -option Ar name value +.Pa network.nix +. +. +. +.Sh DESCRIPTION +. +This command builds a network of QEMU\-KVM virtual machines of a Nix expression +specifying a network of NixOS machines. The virtual network can be started by +executing the +.Pa bin/run-vms +shell script that is generated by this command. By default, a +.Pa result +symlink is produced that points to the generated virtual network. +. +.Pp +A network Nix expression has the following structure: +.Bd -literal -offset indent +{ + test1 = {pkgs, config, ...}: + { + services.openssh.enable = true; + nixpkgs.localSystem.system = "i686-linux"; + deployment.targetHost = "test1.example.net"; + + # Other NixOS options + }; + + test2 = {pkgs, config, ...}: + { + services.openssh.enable = true; + services.httpd.enable = true; + environment.systemPackages = [ pkgs.lynx ]; + nixpkgs.localSystem.system = "x86_64-linux"; + deployment.targetHost = "test2.example.net"; + + # Other NixOS options + }; +} +.Ed +. +.Pp +Each attribute in the expression represents a machine in the network +.Ns (e.g. +.Va test1 +and +.Va test2 Ns +) referring to a function defining a NixOS configuration. In each NixOS +configuration, two attributes have a special meaning. The +.Va deployment.targetHost +specifies the address (domain name or IP address) of the system which is used by +.Ic ssh +to perform remote deployment operations. The +.Va nixpkgs.localSystem.system +attribute can be used to specify an architecture for the target machine, such as +.Ql i686-linux +which builds a 32-bit NixOS configuration. Omitting this property will build the +configuration for the same architecture as the host system. +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -show-trace +Shows a trace of the output. +. +.It Fl -no-out-link +Do not create a +.Pa result +symlink. +. +.It Fl h , -help +Shows the usage of this command to the user. +. +.It Fl -option Ar name Va value +Set the Nix configuration option +.Va name +to +.Va value Ns +\&. This overrides settings in the Nix configuration file (see +.Xr nix.conf 5 Ns +). +.El +. +. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/modules/installer/tools/manpages/nixos-enter.8 b/nixos/modules/installer/tools/manpages/nixos-enter.8 new file mode 100644 index 00000000000..646f92199d6 --- /dev/null +++ b/nixos/modules/installer/tools/manpages/nixos-enter.8 @@ -0,0 +1,72 @@ +.Dd January 1, 1980 +.Dt nixos-enter 8 +.Os +.Sh NAME +.Nm nixos-enter +.Nd run a command in a NixOS chroot environment +. +. +. +.Sh SYNOPSIS +.Nm nixos-enter +.Op Fl -root Ar root +.Op Fl -system Ar system +.Op Fl -command | c Ar shell-command +.Op Fl -silent +.Op Fl -help +.Op Fl - Ar arguments ... +. +. +. +.Sh DESCRIPTION +This command runs a command in a NixOS chroot environment, that is, in a filesystem hierarchy previously prepared using +.Xr nixos-install 8 . +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -root Ar root +The path to the NixOS system you want to enter. It defaults to +.Pa /mnt Ns +\&. +.It Fl -system Ar system +The NixOS system configuration to use. It defaults to +.Pa /nix/var/nix/profiles/system Ns +\&. You can enter a previous NixOS configuration by specifying a path such as +.Pa /nix/var/nix/profiles/system-106-link Ns +\&. +. +.It Fl -command Ar shell-command , Fl c Ar shell-command +The bash command to execute. +. +.It Fl -silent +Suppresses all output from the activation script of the target system. +. +.It Fl - +Interpret the remaining arguments as the program name and arguments to be invoked. +The program is not executed in a shell. +.El +. +. +. +.Sh EXAMPLES +.Bl -tag -width indent +.It Ic nixos-enter --root /mnt +Start an interactive shell in the NixOS installation in +.Pa /mnt Ns . +. +.It Ic nixos-enter -c 'ls -l /; cat /proc/mounts' +Run a shell command. +. +.It Ic nixos-enter -- cat /proc/mounts +Run a non-shell command. +.El +. +. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/modules/installer/tools/manpages/nixos-generate-config.8 b/nixos/modules/installer/tools/manpages/nixos-generate-config.8 new file mode 100644 index 00000000000..1b95599e156 --- /dev/null +++ b/nixos/modules/installer/tools/manpages/nixos-generate-config.8 @@ -0,0 +1,165 @@ +.Dd January 1, 1980 +.Dt nixos-generate-config 8 +.Os +.Sh NAME +.Nm nixos-generate-config +.Nd generate NixOS configuration modules +. +. +. +.Sh SYNOPSIS +.Nm nixos-generate-config +.Op Fl -force +.Op Fl -root Ar root +.Op Fl -dir Ar dir +. +. +. +.Sh DESCRIPTION +This command writes two NixOS configuration modules: +.Bl -tag -width indent +.It Pa /etc/nixos/hardware-configuration.nix +This module sets NixOS configuration options based on your current hardware +configuration. In particular, it sets the +.Va fileSystem +option to reflect all currently mounted file systems, the +.Va swapDevices +option to reflect active swap devices, and the +.Va boot.initrd.* +options to ensure that the initial ramdisk contains any kernel modules necessary +for mounting the root file system. +.Pp +If this file already exists, it is overwritten. Thus, you should not modify it +manually. Rather, you should include it from your +.Pa /etc/nixos/configuration.nix Ns +, and re-run +.Nm +to update it whenever your hardware configuration changes. +. +.It Pa /etc/nixos/configuration.nix +This is the main NixOS system configuration module. If it already exists, it’s +left unchanged. Otherwise, +.Nm +will write a template for you to customise. +.El +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -root Ar root +If this option is given, treat the directory +.Ar root +as the root of the file system. This means that configuration files will be written to +.Ql Ar root Ns /etc/nixos Ns +, and that any file systems outside of +.Ar root +are ignored for the purpose of generating the +.Va fileSystems +option. +. +.It Fl -dir Ar dir +If this option is given, write the configuration files to the directory +.Ar dir +instead of +.Pa /etc/nixos Ns +\&. +. +.It Fl -force +Overwrite +.Pa /etc/nixos/configuration.nix +if it already exists. +. +.It Fl -no-filesystems +Omit everything concerning file systems and swap devices from the hardware configuration. +. +.It Fl -show-hardware-config +Don't generate +.Pa configuration.nix +or +.Pa hardware-configuration.nix +and print the hardware configuration to stdout only. +.El +. +. +. +.Sh EXAMPLES +This command is typically used during NixOS installation to write initial +configuration modules. For example, if you created and mounted the target file +systems on +.Pa /mnt +and +.Pa /mnt/boot Ns +, you would run: +.Bd -literal -offset indent +$ nixos-generate-config --root /mnt +.Ed +. +.Pp +The resulting file +.Pa /mnt/etc/nixos/hardware-configuration.nix +might look like this: +.Bd -literal -offset indent +# Do not modify this file! It was generated by 'nixos-generate-config' +# and may be overwritten by future invocations. Please make changes +# to /etc/nixos/configuration.nix instead. +{ config, pkgs, ... }: + +{ + imports = + [ + ]; + + boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ]; + boot.kernelModules = [ "kvm-intel" ]; + boot.extraModulePackages = [ ]; + + fileSystems."/" = + { device = "/dev/disk/by-label/nixos"; + fsType = "ext3"; + options = [ "rw" "data=ordered" "relatime" ]; + }; + + fileSystems."/boot" = + { device = "/dev/sda1"; + fsType = "ext3"; + options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ]; + }; + + swapDevices = + [ { device = "/dev/sda2"; } + ]; + + nix.maxJobs = 8; +} +.Ed +. +.Pp +It will also create a basic +.Pa /mnt/etc/nixos/configuration.nix Ns +, which you should edit to customise the logical configuration of your system. \ +This file includes the result of the hardware scan as follows: +.Bd -literal -offset indent +imports = [ ./hardware-configuration.nix ]; +.Ed +. +.Pp +After installation, if your hardware configuration changes, you can run: +.Bd -literal -offset indent +$ nixos-generate-config +.Ed +. +.Pp +to update +.Pa /etc/nixos/hardware-configuration.nix Ns +\&. Your +.Pa /etc/nixos/configuration.nix +will +.Em not +be overwritten. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/modules/installer/tools/manpages/nixos-install.8 b/nixos/modules/installer/tools/manpages/nixos-install.8 new file mode 100644 index 00000000000..c6c8ed15224 --- /dev/null +++ b/nixos/modules/installer/tools/manpages/nixos-install.8 @@ -0,0 +1,191 @@ +.Dd January 1, 1980 +.Dt nixos-install 8 +.Os +.Sh NAME +.Nm nixos-install +.Nd install bootloader and NixOS +. +. +. +.Sh SYNOPSIS +.Nm nixos-install +.Op Fl -verbose | v +.Op Fl I Ar path +.Op Fl -root Ar root +.Op Fl -system Ar path +.Op Fl -flake Ar flake-uri +.Op Fl -impure +.Op Fl -channel Ar channel +.Op Fl -no-channel-copy +.Op Fl -no-root-password | -no-root-passwd +.Op Fl -no-bootloader +.Op Fl -max-jobs | j Ar number +.Op Fl -cores Ar number +.Op Fl -option Ar name value +.Op Fl -show-trace +.Op Fl -keep-going +.Op Fl -help +. +. +. +.Sh DESCRIPTION +This command installs NixOS in the file system mounted on +.Pa /mnt Ns +, based on the NixOS configuration specified in +.Pa /mnt/etc/nixos/configuration.nix Ns +\&. It performs the following steps: +. +.Bl -enum +.It +It copies Nix and its dependencies to +.Pa /mnt/nix/store Ns +\&. +. +.It +It runs Nix in +.Pa /mnt +to build the NixOS configuration specified in +.Pa /mnt/etc/nixos/configuration.nix Ns +\&. +. +.It +It installs the current channel +.Dq nixos +in the target channel profile (unless +.Fl -no-channel-copy +is specified). +. +.It +It installs the GRUB boot loader on the device specified in the option +.Va boot.loader.grub.device +(unless +.Fl -no-bootloader +is specified), and generates a GRUB configuration file that boots into the NixOS +configuration just installed. +. +.It +It prompts you for a password for the root account (unless +.Fl -no-root-password +is specified). +.El +. +.Pp +This command is idempotent: if it is interrupted or fails due to a temporary +problem (e.g. a network issue), you can safely re-run it. +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -verbose , v +Increases the level of verbosity of diagnostic messages printed on standard +error. For each Nix operation, the information printed on standard output is +well-defined; any diagnostic information is printed on standard error, never on +standard output. +.Pp +Please note that this option may be specified repeatedly. +. +.It Fl -root Ar root +Defaults to +.Pa /mnt Ns +\&. If this option is given, treat the directory +.Ar root +as the root of the NixOS installation. +. +.It Fl -system Ar path +If this option is provided, +.Nm +will install the specified closure rather than attempt to build one from +.Pa /mnt/etc/nixos/configuration.nix Ns +\&. +.Pp +The closure must be an appropriately configured NixOS system, with boot loader +and partition configuration that fits the target host. Such a closure is +typically obtained with a command such as +.Ic nix-build -I nixos-config=./configuration.nix '' -A system --no-out-link Ns +\&. +. +.It Fl -flake Ar flake-uri Ns # Ns Ar name +Build the NixOS system from the specified flake. The flake must contain an +output named +.Ql nixosConfigurations. Ns Ar name Ns +\&. +. +.It Fl -channel Ar channel +If this option is provided, do not copy the current +.Dq nixos +channel to the target host. Instead, use the specified derivation. +. +.It Fl I Ar Path +Add a path to the Nix expression search path. This option may be given multiple +times. See the +.Ev NIX_PATH +environment variable for information on the semantics of the Nix search path. Paths added through +.Fl I +take precedence over +.Ev NIX_PATH Ns +\&. +. +.It Fl -max-jobs , j Ar number +Sets the maximum number of build jobs that Nix will perform in parallel to the +specified number. The default is 1. A higher value is useful on SMP systems or +to exploit I/O latency. +. +.It Fl -cores Ar N +Sets the value of the +.Ev NIX_BUILD_CORES +environment variable in the invocation of builders. Builders can use this +variable at their discretion to control the maximum amount of parallelism. For +instance, in Nixpkgs, if the derivation attribute +.Va enableParallelBuilding +is set to true, the builder passes the +.Fl j Ns Va N +flag to GNU Make. The value 0 means that the builder should use all available CPU cores in the system. +. +.It Fl -option Ar name value +Set the Nix configuration option +.Ar name +to +.Ar value Ns +\&. +. +.It Fl -show-trace +Causes Nix to print out a stack trace in case of Nix expression evaluation errors. +. +.It Fl -keep-going +Causes Nix to continue building derivations as far as possible in the face of failed builds. +. +.It Fl -help +Synonym for +.Ic man nixos-install Ns +\&. +.El +. +. +. +.Sh EXAMPLES +A typical NixOS installation is done by creating and mounting a file system on +.Pa /mnt Ns +, generating a NixOS configuration in +.Pa /mnt/etc/nixos/configuration.nix Ns +, and running +.Nm Ns +\&. For instance, if we want to install NixOS on an ext4 file system created in +.Pa /dev/sda1 Ns +: +.Bd -literal -offset indent +$ mkfs.ext4 /dev/sda1 +$ mount /dev/sda1 /mnt +$ nixos-generate-config --root /mnt +$ # edit /mnt/etc/nixos/configuration.nix +$ nixos-install +$ reboot +.Ed +. +. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/modules/installer/tools/manpages/nixos-version.8 b/nixos/modules/installer/tools/manpages/nixos-version.8 new file mode 100644 index 00000000000..f661611599f --- /dev/null +++ b/nixos/modules/installer/tools/manpages/nixos-version.8 @@ -0,0 +1,86 @@ +.Dd January 1, 1980 +.Dt nixos-version 8 +.Os +.Sh NAME +.Nm nixos-version +.Nd show the NixOS version +. +. +. +.Sh SYNOPSIS +.Nm nixos-version +.Op Fl -hash +.Op Fl -revision +.Op Fl -configuration-revision +.Op Fl -json +. +. +. +.Sh DESCRIPTION +This command shows the version of the currently active NixOS configuration. For example: +.Bd -literal -offset indent +$ nixos-version +16.03.1011.6317da4 (Emu) +.Ed +. +.Pp +The version consists of the following elements: +.Bl -tag -width indent +.It Ql 16.03 +The NixOS release, indicating the year and month in which it was released +(e.g. March 2016). +.It Ql 1011 +The number of commits in the Nixpkgs Git repository between the start of the +release branch and the commit from which this version was built. This ensures +that NixOS versions are monotonically increasing. It is +.Ql git +when the current NixOS configuration was built from a checkout of the Nixpkgs +Git repository rather than from a NixOS channel. +.It Ql 6317da4 +The first 7 characters of the commit in the Nixpkgs Git repository from which +this version was built. +.It Ql Emu +The code name of the NixOS release. The first letter of the code name indicates +that this is the N'th stable NixOS release; for example, Emu is the fifth +release. +.El +. +. +. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl -hash , -revision +Show the full SHA1 hash of the Git commit from which this configuration was +built, e.g. +.Bd -literal -offset indent +$ nixos-version --hash +6317da40006f6bc2480c6781999c52d88dde2acf +.Ed +. +.It Fl -configuration-revision +Show the configuration revision if available. This could be the full SHA1 hash +of the Git commit of the system flake, if you add +.Bd -literal -offset indent +{ system.configurationRevision = self.rev or "dirty"; } +.Ed +.Pp +to the +.Ql modules +array of your flake.nix system configuration e.g. +.Bd -literal -offset indent +$ nixos-version --configuration-revision +aa314ebd1592f6cdd53cb5bba8bcae97d9323de8 +.Ed +. +.It Fl -json +Print a JSON representation of the versions of NixOS and the top-level +configuration flake. +.El +. +. +. +.Sh AUTHORS +.An -nosplit +.An Eelco Dolstra +and +.An the Nixpkgs/NixOS contributors diff --git a/nixos/modules/installer/tools/tools.nix b/nixos/modules/installer/tools/tools.nix index 4dce4f99805..6564b583464 100644 --- a/nixos/modules/installer/tools/tools.nix +++ b/nixos/modules/installer/tools/tools.nix @@ -9,12 +9,19 @@ let makeProg = args: pkgs.substituteAll (args // { dir = "bin"; isExecutable = true; + nativeBuildInputs = [ + pkgs.installShellFiles + ]; + postInstall = '' + installManPage ${args.manPage} + ''; }); nixos-build-vms = makeProg { name = "nixos-build-vms"; src = ./nixos-build-vms/nixos-build-vms.sh; inherit (pkgs) runtimeShell; + manPage = ./manpages/nixos-build-vms.8; }; nixos-install = makeProg { @@ -27,6 +34,7 @@ let nixos-enter pkgs.util-linuxMinimal ]; + manPage = ./manpages/nixos-install.8; }; nixos-rebuild = pkgs.nixos-rebuild.override { nix = config.nix.package.out; }; @@ -40,6 +48,7 @@ let btrfs = "${pkgs.btrfs-progs}/bin/btrfs"; inherit (config.system.nixos-generate-config) configuration desktopConfiguration; xserverEnabled = config.services.xserver.enable; + manPage = ./manpages/nixos-generate-config.8; }; inherit (pkgs) nixos-option; @@ -57,6 +66,7 @@ let } // optionalAttrs (config.system.configurationRevision != null) { configurationRevision = config.system.configurationRevision; }); + manPage = ./manpages/nixos-version.8; }; nixos-enter = makeProg { @@ -66,6 +76,7 @@ let path = makeBinPath [ pkgs.util-linuxMinimal ]; + manPage = ./manpages/nixos-enter.8; }; in -- cgit 1.4.1 From 924a07dc227b69b53e3f43d2d08996d33b364c92 Mon Sep 17 00:00:00 2001 From: Doron Behar Date: Sat, 12 Aug 2023 18:47:43 +0300 Subject: nixos/doc: Improve documentation of documentation - Move contents of README.md from nixos/modules/installer/tools/manpages/ to nixos/doc/manual/contributing-to-this-manual.chapter.md. - Don't mention DocBook as its obsolete and too specific. - Rename derivation attribute name of configuration.nix(5) manual page, both on the `contributing-to-this-manual.chapter.md`, and in other places. --- .../manual/contributing-to-this-manual.chapter.md | 91 +++++++++++++++++++--- nixos/doc/manual/default.nix | 2 +- nixos/modules/installer/tools/manpages/README.md | 57 -------------- nixos/modules/misc/documentation.nix | 2 +- nixos/release.nix | 2 +- pkgs/tools/nix/nixos-install-tools/default.nix | 2 +- 6 files changed, 86 insertions(+), 70 deletions(-) delete mode 100644 nixos/modules/installer/tools/manpages/README.md (limited to 'nixos/modules/installer/tools') diff --git a/nixos/doc/manual/contributing-to-this-manual.chapter.md b/nixos/doc/manual/contributing-to-this-manual.chapter.md index 4633c7e1b05..b7282d65c41 100644 --- a/nixos/doc/manual/contributing-to-this-manual.chapter.md +++ b/nixos/doc/manual/contributing-to-this-manual.chapter.md @@ -6,6 +6,7 @@ You can quickly check your edits with the following: ```ShellSession $ cd /path/to/nixpkgs +$ $EDITOR doc/nixos/manual/... # edit the manual $ nix-build nixos/release.nix -A manual.x86_64-linux ``` @@ -13,24 +14,96 @@ If the build succeeds, the manual will be in `./result/share/doc/nixos/index.htm There's also [a convenient development daemon](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-devmode). -**Contributing to the man pages** +The above instructions don't deal with the appendix of available `configuration.nix` options, and the manual pages related to NixOS. These are built, and written in a different location and in a different format, as explained in the next sections. -The man pages are written in [DocBook] which is XML. +## Contributing to the `configuration.nix` options documentation {#sec-contributing-options} -To see what your edits look like: +The documentation for all the different `configuration.nix` options is automatically generated by reading the `description`s of all the NixOS options defined at `nixos/modules/`. If you want to improve such `description`, find it in the `nixos/modules/` directory, and edit it and open a pull request. + +To see how your changes render on the web, run again: + +```ShellSession +$ nix-build nixos/release.nix -A manual.x86_64-linux +``` + +And you'll see the changes to the appendix in the path `result/share/doc/nixos/options.html`. + +You can also build only the `configuration.nix(5)` manual page, via: ```ShellSession $ cd /path/to/nixpkgs -$ nix-build nixos/release.nix -A manpages.x86_64-linux +$ nix-build nixos/release.nix -A nixos-configuration-reference-manpage.x86_64-linux ``` -You can then read the man page you edited by running +And observe the result via: ```ShellSession -$ man --manpath=result/share/man nixos-rebuild # Replace nixos-rebuild with the command whose manual you edited +$ man --local-file result/share/man/man5/configuration.nix.5 +``` + +If you're on a different architecture that's supported by NixOS (check file `nixos/release.nix` on Nixpkgs' repository) then replace `x86_64-linux` with the architecture. `nix-build` will complain otherwise, but should also tell you which architecture you have + the supported ones. + +## Contributing to `nixos-*` tools' manpages {#sec-contributing-nixos-tools} + +The manual pages for the tools available in the installation image can be found in Nixpkgs' by running (e.g for `nixos-rebuild`): + +```ShellSession +$ git ls | grep nixos-rebuild.8 +``` + +Man pages are written in [`mdoc(7)` format](https://mandoc.bsd.lv/man/mdoc.7.html) and should be portable between mandoc and groff for rendering (though minor differences may occur, mandoc and groff seem to have slightly different spacing rules.) + +For previewing edited files, you can just run `man --local-file path/to/file.8` and you will see it rendered. + +Being written in `mdoc`, these manpages use semantic markup. This file provides a guideline on where to apply which of the semantic elements of `mdoc`. + +### Command lines and arguments {#ssec-contributing-nixos-tools-cli-and-args} + +In any manpage, commands, flags and arguments to the *current* executable should be marked according to their semantics. Commands, flags and arguments passed to *other* executables should not be marked like this and should instead be considered as code examples and marked with `Ql`. + +- Use `Fl` to mark flag arguments, `Ar` for their arguments. +- Repeating arguments should be marked by adding ellipses (`...`). +- Use `Cm` to mark literal string arguments, e.g. the `boot` command argument passed to `nixos-rebuild`. +- Optional flags or arguments should be marked with `Op`. This includes optional repeating arguments. +- Required flags or arguments should not be marked. +- Mutually exclusive groups of arguments should be enclosed in curly brackets, preferably created with `Bro`/`Brc` blocks. + +When an argument is used in an example it should be marked up with `Ar` again to differentiate it from a constant. For example, a command with a `--host name` flag that calls ssh to retrieve the host's local time would signify this thusly: +``` +This will run +.Ic ssh Ar name Ic time +to retrieve the remote time. ``` -If you're on a different architecture that's supported by NixOS (check nixos/release.nix) then replace `x86_64-linux` with the architecture. -`nix-build` will complain otherwise, but should also tell you which architecture you have + the supported ones. +### Paths, NixOS options, environment variables {#ssec-contributing-nixos-tools-options-and-environment} + +Constant paths should be marked with `Pa`, NixOS options with `Va`, and environment variables with `Ev`. + +Generated paths, e.g. `result/bin/run-hostname-vm` (where `hostname` is a variable or arguments) should be marked as `Ql` inline literals with their variable components marked appropriately. + + - Taking `hostname` from an argument become `.Ql result/bin/run- Ns Ar hostname Ns -vm` + - Taking `hostname` from a variable otherwise defined becomes `.Ql result/bin/run- Ns Va hostname Ns -vm` + +### Code examples and other commands {#ssec-contributing-nixos-tools-code-examples} -[DocBook]: https://en.wikipedia.org/wiki/DocBook +In free text names and complete invocations of other commands (e.g. `ssh` or `tar -xvf src.tar`) should be marked with `Ic`, fragments of command lines should be marked with `Ql`. + +Larger code blocks or those that cannot be shown inline should use indented literal display block markup for their contents, i.e. + +``` +.Bd -literal -offset indent +... +.Ed +``` + +Contents of code blocks may be marked up further, e.g. if they refer to arguments that will be substituted into them: + +``` +.Bd -literal -offset indent +{ + options.hostname = "\c +.Ar hostname Ns \c +"; +} +.Ed +``` diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 962c74edee8..85eab08a457 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -185,7 +185,7 @@ in rec { # Generate the configuration.nix manual package - configuration-manual = runCommand "nixos-manpages" + nixos-configuration-reference-manpage = runCommand "nixos-configuration-reference-manpage" { nativeBuildInputs = [ buildPackages.installShellFiles buildPackages.nixos-render-docs diff --git a/nixos/modules/installer/tools/manpages/README.md b/nixos/modules/installer/tools/manpages/README.md deleted file mode 100644 index 05cb83902c7..00000000000 --- a/nixos/modules/installer/tools/manpages/README.md +++ /dev/null @@ -1,57 +0,0 @@ -# NixOS manpages - -This is the collection of NixOS manpages, excluding `configuration.nix(5)`. - -Man pages are written in [`mdoc(7)` format](https://mandoc.bsd.lv/man/mdoc.7.html) and should be portable between mandoc and groff for rendering (though minor differences may occur, mandoc and groff seem to have slightly different spacing rules.) - -For previewing edited files, you can just run `man -l path/to/file.8` and you will see it rendered. - -Being written in `mdoc` these manpages use semantic markup. This file provides a guideline on where to apply which of the semantic elements of `mdoc`. - -### Command lines and arguments - -In any manpage, commands, flags and arguments to the *current* executable should be marked according to their semantics. Commands, flags and arguments passed to *other* executables should not be marked like this and should instead be considered as code examples and marked with `Ql`. - - - Use `Fl` to mark flag arguments, `Ar` for their arguments. - - Repeating arguments should be marked by adding ellipses (`...`). - - Use `Cm` to mark literal string arguments, e.g. the `boot` command argument passed to `nixos-rebuild`. - - Optional flags or arguments should be marked with `Op`. This includes optional repeating arguments. - - Required flags or arguments should not be marked. - - Mutually exclusive groups of arguments should be enclosed in curly brackets, preferably created with `Bro`/`Brc` blocks. - -When an argument is used in an example it should be marked up with `Ar` again to differentiate it from a constant. For example, a command with a `--host name` flag that calls ssh to retrieve the host's local time would signify this thusly: -``` -This will run -.Ic ssh Ar name Ic time -to retrieve the remote time. -``` - -### Paths, NixOS options, environment variables - -Constant paths should be marked with `Pa`, NixOS options with `Va`, and environment variables with `Ev`. - -Generated paths, e.g. `result/bin/run-hostname-vm` (where `hostname` is a variable or arguments) should be marked as `Ql` inline literals with their variable components marked appropriately. - - - Taking `hostname` from an argument become `.Ql result/bin/run- Ns Ar hostname Ns -vm` - - Taking `hostname` from a variable otherwise defined becomes `.Ql result/bin/run- Ns Va hostname Ns -vm` - -### Code examples and other commands - -In free text names and complete invocations of other commands (e.g. `ssh` or `tar -xvf src.tar`) should be marked with `Ic`, fragments of command lines should be marked with `Ql`. - -Larger code blocks or those that cannot be shown inline should use indented literal display block markup for their contents, i.e. -``` -.Bd -literal -offset indent -... -.Ed -``` -Contents of code blocks may be marked up further, e.g. if they refer to arguments that will be substituted into them: -``` -.Bd -literal -offset indent -{ - options.hostname = "\c -.Ar hostname Ns \c -"; -} -.Ed -``` diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix index c94f5c53d9c..46462c5abd4 100644 --- a/nixos/modules/misc/documentation.nix +++ b/nixos/modules/misc/documentation.nix @@ -346,7 +346,7 @@ in system.build.manual = manual; environment.systemPackages = [] - ++ optional cfg.man.enable manual.configuration-manual + ++ optional cfg.man.enable manual.nixos-configuration-reference-manpage ++ optionals cfg.doc.enable [ manual.manualHTML nixos-help ]; }) diff --git a/nixos/release.nix b/nixos/release.nix index 2d7661e935f..6da6faab73b 100644 --- a/nixos/release.nix +++ b/nixos/release.nix @@ -143,7 +143,7 @@ in rec { manualHTML = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manualHTML); manual = manualHTML; # TODO(@oxij): remove eventually manualEpub = (buildFromConfig ({ ... }: { }) (config: config.system.build.manual.manualEpub)); - manpages = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.configuration-manual); + nixos-configuration-reference-manpage = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.nixos-configuration-reference-manpage); options = (buildFromConfig ({ ... }: { }) (config: config.system.build.manual.optionsJSON)).x86_64-linux; diff --git a/pkgs/tools/nix/nixos-install-tools/default.nix b/pkgs/tools/nix/nixos-install-tools/default.nix index 37a3f880536..e0b24a4e70d 100644 --- a/pkgs/tools/nix/nixos-install-tools/default.nix +++ b/pkgs/tools/nix/nixos-install-tools/default.nix @@ -20,7 +20,7 @@ in inherit (config.system.build) nixos-install nixos-generate-config nixos-enter; - inherit (config.system.build.manual) configuration-manual; + inherit (config.system.build.manual) nixos-configuration-reference-manpage; }; extraOutputsToInstall = ["man"]; -- cgit 1.4.1