From 244f6537c05a6d68c2e48d02ad9456854960b0d0 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Sun, 19 Jan 2025 17:04:09 +0100 Subject: [PATCH] shebang scripts: clarify explanation of parameters using formatting (#1097) Prompted by https://github.com/NixOS/nix.dev/issues/1096 It may not be immediately obvious that the paragraphs following the code sample explain the invocation parameters. Making them a list should let that part stand out enough to slow down reading a bit. --- .../first-steps/reproducible-scripts.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/source/tutorials/first-steps/reproducible-scripts.md b/source/tutorials/first-steps/reproducible-scripts.md index c0a1ec930..550990617 100644 --- a/source/tutorials/first-steps/reproducible-scripts.md +++ b/source/tutorials/first-steps/reproducible-scripts.md @@ -64,22 +64,24 @@ curl https://github.com/NixOS/nixpkgs/releases.atom | xml2json | jq . ``` The first line is a standard shebang. -The additional shebang lines are a Nix-specific construct. +The additional shebang lines are a Nix-specific construct: -We specify `bash` as the interpreter for the rest of the file with the `-i` option. +- With the `-i` option, `bash` is specified as the interpreter for the rest of the file. -We enable the `--pure` option to prevent the script from implicitly using programs that may already exist on the system that will run the script. +- In this case, the `--pure` option is enabled to prevent the script from implicitly using programs that may already exist on the system on which the script is run. -With the `-p` option we specify the packages required for the script to run. -The command `xml2json` is provided by the package `python3Packages.xmljson`, while `bash`, `jq`, and `curl` are provided by packages of the same name. +- The `-p` option lists the packages required for the script to run. + + The command `xml2json` is provided by the package `python3Packages.xmljson`, while `bash`, `jq`, and `curl` are provided by packages of the same name. `cacert` must be present for SSL authentication to work. -:::{tip} -Use [search.nixos.org](https://search.nixos.org/packages) to find packages providing the program you need. -::: + :::{tip} + Use [search.nixos.org](https://search.nixos.org/packages) to find packages providing the program you need. + ::: + +- The parameter of `-I` refers to a specific Git commit of the Nixpkgs repository. -The parameter of `-I` refers to a specific Git commit of the Nixpkgs repository. -This ensures that the script will always run with the exact same packages versions, everywhere. + This ensures that the script will always run with the exact same packages versions, everywhere. Make the script executable: