From 68e6cc58316ba5952662420f76ae2ba1d8f2d8a6 Mon Sep 17 00:00:00 2001 From: Doron Behar Date: Sat, 12 Aug 2023 12:52:46 +0300 Subject: [PATCH 1/5] nixos-rebuild: Include manual page in the package --- pkgs/os-specific/linux/nixos-rebuild/default.nix | 7 +++++++ .../os-specific/linux/nixos-rebuild}/nixos-rebuild.8 | 0 2 files changed, 7 insertions(+) rename {nixos/doc/manual/manpages => pkgs/os-specific/linux/nixos-rebuild}/nixos-rebuild.8 (100%) diff --git a/pkgs/os-specific/linux/nixos-rebuild/default.nix b/pkgs/os-specific/linux/nixos-rebuild/default.nix index b0a00972eca2..b871c63e36d3 100644 --- a/pkgs/os-specific/linux/nixos-rebuild/default.nix +++ b/pkgs/os-specific/linux/nixos-rebuild/default.nix @@ -6,6 +6,7 @@ , nix , lib , nixosTests +, installShellFiles }: let fallback = import ./../../../../nixos/modules/installer/tools/nix-fallback-paths.nix; @@ -20,6 +21,12 @@ substituteAll { nix_i686_linux = fallback.i686-linux; nix_aarch64_linux = fallback.aarch64-linux; path = lib.makeBinPath [ coreutils gnused gnugrep ]; + nativeBuildInputs = [ + installShellFiles + ]; + postInstall = '' + installManPage ${./nixos-rebuild.8} + ''; # run some a simple installer tests to make sure nixos-rebuild still works for them passthru.tests = { diff --git a/nixos/doc/manual/manpages/nixos-rebuild.8 b/pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8 similarity index 100% rename from nixos/doc/manual/manpages/nixos-rebuild.8 rename to pkgs/os-specific/linux/nixos-rebuild/nixos-rebuild.8 From 9d0bb6e67a4a1922fefc9c0a35bd5b1f0482aaac Mon Sep 17 00:00:00 2001 From: Doron Behar Date: Sat, 12 Aug 2023 12:56:33 +0300 Subject: [PATCH 2/5] nixos-option: Include manual page in the package --- pkgs/tools/nix/nixos-option/default.nix | 27 ++++++++++++++++--- .../tools/nix/nixos-option}/nixos-option.8 | 0 2 files changed, 23 insertions(+), 4 deletions(-) rename {nixos/doc/manual/manpages => pkgs/tools/nix/nixos-option}/nixos-option.8 (100%) diff --git a/pkgs/tools/nix/nixos-option/default.nix b/pkgs/tools/nix/nixos-option/default.nix index 56cb3e130038..7cca1eb7b38d 100644 --- a/pkgs/tools/nix/nixos-option/default.nix +++ b/pkgs/tools/nix/nixos-option/default.nix @@ -1,14 +1,33 @@ -{ lib, stdenv, boost, cmake, pkg-config, nix }: +{ lib +, stdenv +, boost +, cmake +, pkg-config +, installShellFiles +, nix +}: stdenv.mkDerivation { name = "nixos-option"; src = ./.; + postInstall = '' + installManPage ${./nixos-option.8} + ''; strictDeps = true; - nativeBuildInputs = [ cmake pkg-config ]; - buildInputs = [ boost nix ]; - cmakeFlags = [ "-DNIX_DEV_INCLUDEPATH=${nix.dev}/include/nix" ]; + nativeBuildInputs = [ + cmake + pkg-config + installShellFiles + ]; + buildInputs = [ + boost + nix + ]; + cmakeFlags = [ + "-DNIX_DEV_INCLUDEPATH=${nix.dev}/include/nix" + ]; meta = with lib; { license = licenses.lgpl2Plus; diff --git a/nixos/doc/manual/manpages/nixos-option.8 b/pkgs/tools/nix/nixos-option/nixos-option.8 similarity index 100% rename from nixos/doc/manual/manpages/nixos-option.8 rename to pkgs/tools/nix/nixos-option/nixos-option.8 From 32f75a0f2af55b50061629fd4e51221f15ada457 Mon Sep 17 00:00:00 2001 From: Doron Behar Date: Sat, 12 Aug 2023 13:13:14 +0300 Subject: [PATCH 3/5] 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/doc/manual/default.nix | 6 ++---- .../installer/tools}/manpages/README.md | 0 .../installer/tools}/manpages/nixos-build-vms.8 | 0 .../installer/tools}/manpages/nixos-enter.8 | 0 .../installer/tools}/manpages/nixos-generate-config.8 | 0 .../installer/tools}/manpages/nixos-install.8 | 0 .../installer/tools}/manpages/nixos-version.8 | 0 nixos/modules/installer/tools/tools.nix | 11 +++++++++++ nixos/modules/misc/documentation.nix | 2 +- nixos/release.nix | 2 +- pkgs/tools/nix/nixos-install-tools/default.nix | 3 +-- 11 files changed, 16 insertions(+), 8 deletions(-) rename nixos/{doc/manual => modules/installer/tools}/manpages/README.md (100%) rename nixos/{doc/manual => modules/installer/tools}/manpages/nixos-build-vms.8 (100%) rename nixos/{doc/manual => modules/installer/tools}/manpages/nixos-enter.8 (100%) rename nixos/{doc/manual => modules/installer/tools}/manpages/nixos-generate-config.8 (100%) rename nixos/{doc/manual => modules/installer/tools}/manpages/nixos-install.8 (100%) rename nixos/{doc/manual => modules/installer/tools}/manpages/nixos-version.8 (100%) diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 902dee701801..962c74edee89 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -184,8 +184,8 @@ in rec { ''; - # Generate the NixOS manpages. - manpages = runCommand "nixos-manpages" + # Generate the configuration.nix manual package + configuration-manual = runCommand "nixos-manpages" { nativeBuildInputs = [ buildPackages.installShellFiles buildPackages.nixos-render-docs @@ -194,8 +194,6 @@ in rec { } '' # Generate manpages. - mkdir -p $out/share/man/man8 - installManPage ${./manpages}/* mkdir -p $out/share/man/man5 nixos-render-docs -j $NIX_BUILD_CORES options manpage \ --revision ${lib.escapeShellArg revision} \ diff --git a/nixos/doc/manual/manpages/README.md b/nixos/modules/installer/tools/manpages/README.md similarity index 100% rename from nixos/doc/manual/manpages/README.md rename to nixos/modules/installer/tools/manpages/README.md diff --git a/nixos/doc/manual/manpages/nixos-build-vms.8 b/nixos/modules/installer/tools/manpages/nixos-build-vms.8 similarity index 100% rename from nixos/doc/manual/manpages/nixos-build-vms.8 rename to nixos/modules/installer/tools/manpages/nixos-build-vms.8 diff --git a/nixos/doc/manual/manpages/nixos-enter.8 b/nixos/modules/installer/tools/manpages/nixos-enter.8 similarity index 100% rename from nixos/doc/manual/manpages/nixos-enter.8 rename to nixos/modules/installer/tools/manpages/nixos-enter.8 diff --git a/nixos/doc/manual/manpages/nixos-generate-config.8 b/nixos/modules/installer/tools/manpages/nixos-generate-config.8 similarity index 100% rename from nixos/doc/manual/manpages/nixos-generate-config.8 rename to nixos/modules/installer/tools/manpages/nixos-generate-config.8 diff --git a/nixos/doc/manual/manpages/nixos-install.8 b/nixos/modules/installer/tools/manpages/nixos-install.8 similarity index 100% rename from nixos/doc/manual/manpages/nixos-install.8 rename to nixos/modules/installer/tools/manpages/nixos-install.8 diff --git a/nixos/doc/manual/manpages/nixos-version.8 b/nixos/modules/installer/tools/manpages/nixos-version.8 similarity index 100% rename from nixos/doc/manual/manpages/nixos-version.8 rename to nixos/modules/installer/tools/manpages/nixos-version.8 diff --git a/nixos/modules/installer/tools/tools.nix b/nixos/modules/installer/tools/tools.nix index 4dce4f998052..6564b583464a 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 diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix index 820450e3ce2a..c94f5c53d9c5 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.manpages + ++ optional cfg.man.enable manual.configuration-manual ++ optionals cfg.doc.enable [ manual.manualHTML nixos-help ]; }) diff --git a/nixos/release.nix b/nixos/release.nix index 93ebe000fc00..2d7661e935f6 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.manpages); + manpages = buildFromConfig ({ ... }: { }) (config: config.system.build.manual.configuration-manual); 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 63f2da0df21c..37a3f880536e 100644 --- a/pkgs/tools/nix/nixos-install-tools/default.nix +++ b/pkgs/tools/nix/nixos-install-tools/default.nix @@ -20,8 +20,7 @@ in inherit (config.system.build) nixos-install nixos-generate-config nixos-enter; - # Required for --help. - inherit (config.system.build.manual) manpages; + inherit (config.system.build.manual) configuration-manual; }; extraOutputsToInstall = ["man"]; From 924a07dc227b69b53e3f43d2d08996d33b364c92 Mon Sep 17 00:00:00 2001 From: Doron Behar Date: Sat, 12 Aug 2023 18:47:43 +0300 Subject: [PATCH 4/5] 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. --- .../contributing-to-this-manual.chapter.md | 91 +++++++++++++++++-- nixos/doc/manual/default.nix | 2 +- .../installer/tools/manpages/README.md | 57 ------------ nixos/modules/misc/documentation.nix | 2 +- nixos/release.nix | 2 +- .../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 diff --git a/nixos/doc/manual/contributing-to-this-manual.chapter.md b/nixos/doc/manual/contributing-to-this-manual.chapter.md index 4633c7e1b058..b7282d65c41e 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 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. +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. -[DocBook]: https://en.wikipedia.org/wiki/DocBook +## 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. +``` + +### 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} + +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 962c74edee89..85eab08a457f 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 05cb83902c74..000000000000 --- 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 c94f5c53d9c5..46462c5abd43 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 2d7661e935f6..6da6faab73be 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 37a3f880536e..e0b24a4e70dd 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"]; From 307da96e176c8e7bdb715115806daaa810be4dfc Mon Sep 17 00:00:00 2001 From: Doron Behar Date: Wed, 16 Aug 2023 06:24:37 +0000 Subject: [PATCH 5/5] nixos/doc: small rephrase in documentation of documentation Co-authored-by: Robert Hensing --- .../contributing-to-this-manual.chapter.md | 18 +++++++++--------- nixos/doc/manual/default.nix | 2 +- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/nixos/doc/manual/contributing-to-this-manual.chapter.md b/nixos/doc/manual/contributing-to-this-manual.chapter.md index b7282d65c41e..4b7a7f47fd3d 100644 --- a/nixos/doc/manual/contributing-to-this-manual.chapter.md +++ b/nixos/doc/manual/contributing-to-this-manual.chapter.md @@ -45,30 +45,30 @@ If you're on a different architecture that's supported by NixOS (check file `nix ## 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`): +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.) +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 (except for minor differences, notably different spacing rules.) -For previewing edited files, you can just run `man --local-file path/to/file.8` and you will see it rendered. +For a preview, run `man --local-file path/to/file.8`. -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`. +Being written in `mdoc`, these manpages use semantic markup. This following subsections provides a guideline on where to apply which semantic elements. ### 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 (`...`). +- Repeating arguments should be marked by adding an ellipsis (spelled with periods, `...`). - 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: +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` option that calls ssh to retrieve the host's local time would signify this thusly: ``` This will run .Ic ssh Ar name Ic time @@ -81,8 +81,8 @@ Constant paths should be marked with `Pa`, NixOS options with `Va`, and environm 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` + - When `hostname` refers to an argument, it becomes `.Ql result/bin/run- Ns Ar hostname Ns -vm` + - When `hostname` refers to a variable, it becomes `.Ql result/bin/run- Ns Va hostname Ns -vm` ### Code examples and other commands {#ssec-contributing-nixos-tools-code-examples} @@ -101,7 +101,7 @@ Contents of code blocks may be marked up further, e.g. if they refer to argument ``` .Bd -literal -offset indent { - options.hostname = "\c + config.networking.hostname = "\c .Ar hostname Ns \c "; } diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 85eab08a457f..a368b16201f8 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -184,7 +184,7 @@ in rec { ''; - # Generate the configuration.nix manual package + # Generate the `man configuration.nix` package nixos-configuration-reference-manpage = runCommand "nixos-configuration-reference-manpage" { nativeBuildInputs = [ buildPackages.installShellFiles