From 83b917a960d1d637f0ad36ab709adba4dd69f8f8 Mon Sep 17 00:00:00 2001 From: LoveIsGrief Date: Fri, 9 Dec 2022 15:05:04 +0100 Subject: nixos/manpages: Explain -I option and how to build manpages When running nixos-rebuild -I, the man page just said "-I path" which could be interpreted as "just a path to nixpkgs", which in fact it actually has the same meaning as NIX_PATH. This is now made clear in the manual, so that when grepping "-I" and "NIX_PATH" one quickly finds the format of the option. I don't know how to link to the "nix manual" as stated in the docbook, so I left that as it is. Additionally, it wasn't clear to me how to actually build the man pages and view the changes I made. That's now in the contributing-to-this-manual.chapter.md. --- .../manual/contributing-to-this-manual.chapter.md | 24 +++++++++++++++- .../contributing-to-this-manual.chapter.xml | 32 +++++++++++++++++++++- nixos/doc/manual/man-nixos-rebuild.xml | 18 ++++++++++-- 3 files changed, 70 insertions(+), 4 deletions(-) diff --git a/nixos/doc/manual/contributing-to-this-manual.chapter.md b/nixos/doc/manual/contributing-to-this-manual.chapter.md index 26813d1042d69..557599809222a 100644 --- a/nixos/doc/manual/contributing-to-this-manual.chapter.md +++ b/nixos/doc/manual/contributing-to-this-manual.chapter.md @@ -1,6 +1,6 @@ # Contributing to this manual {#chap-contributing} -The DocBook and CommonMark sources of NixOS' manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository. +The [DocBook] and CommonMark sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository. You can quickly check your edits with the following: @@ -11,3 +11,25 @@ $ nix-build nixos/release.nix -A manual.x86_64-linux ``` If the build succeeds, the manual will be in `./result/share/doc/nixos/index.html`. + +**Contributing to the man pages** + +The man pages are written in [DocBook] which is XML. + +To see what your edits look like: + +```ShellSession +$ cd /path/to/nixpkgs +$ nix-build nixos/release.nix -A manpages.x86_64-linux +``` + +You can then read the man page you edited by running + +```ShellSession +$ man --manpath=result/share/man nixos-rebuild # Replace nixos-rebuild with the command whose manual you edited +``` + +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. + +[DocBook]: https://en.wikipedia.org/wiki/DocBook diff --git a/nixos/doc/manual/from_md/contributing-to-this-manual.chapter.xml b/nixos/doc/manual/from_md/contributing-to-this-manual.chapter.xml index a9b0c6a5eefa1..99dc5ce30b4b1 100644 --- a/nixos/doc/manual/from_md/contributing-to-this-manual.chapter.xml +++ b/nixos/doc/manual/from_md/contributing-to-this-manual.chapter.xml @@ -1,7 +1,9 @@ Contributing to this manual - The DocBook and CommonMark sources of NixOS’ manual are in the + The + DocBook + and CommonMark sources of the NixOS manual are in the nixos/doc/manual subdirectory of the Nixpkgs @@ -19,4 +21,32 @@ $ nix-build nixos/release.nix -A manual.x86_64-linux If the build succeeds, the manual will be in ./result/share/doc/nixos/index.html. + + Contributing to the man pages + + + The man pages are written in + DocBook + which is XML. + + + To see what your edits look like: + + +$ cd /path/to/nixpkgs +$ nix-build nixos/release.nix -A manpages.x86_64-linux + + + You can then read the man page you edited by running + + +$ man --manpath=result/share/man nixos-rebuild # Replace nixos-rebuild with the command whose manual you edited + + + 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. + diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml index ea96f49fa9772..cab871661a755 100644 --- a/nixos/doc/manual/man-nixos-rebuild.xml +++ b/nixos/doc/manual/man-nixos-rebuild.xml @@ -134,7 +134,7 @@ - path + NIX_PATH @@ -624,7 +624,7 @@ In addition, nixos-rebuild accepts various Nix-related - flags, including / , + flags, including / , , , , , , and / . See the Nix manual for details. @@ -647,6 +647,20 @@ + + + NIX_PATH + + + + A colon-separated list of directories used to look up Nix expressions enclosed in angle brackets (e.g <nixpkgs>). Example + + nixpkgs=./my-nixpkgs + + + + + NIX_SSHOPTS -- cgit 1.4.1