docs: Allow installManPage to take a piped input

doc/hooks/installShellFiles.section.md

@@ -43,11 +43,42 @@ The manpages must have a section suffix, and may optionally be compressed (with
   nativeBuildInputs = [ installShellFiles ];
 
   # Sometimes the manpage file has an undersirable name; e.g. it conflicts with
-  # another software with an equal name. It should be renamed before being
-  # installed via installManPage
+  # another software with an equal name. To install it with a different name,
+  # the installed name must be provided before the path to the file.
+  #
+  # Below install a manpage "foobar.1" from the source file "./foobar.1", and
+  # also installs the manpage "fromsea.3" from the source file "./delmar.3".
   postInstall = ''
-    mv fromsea.3 delmar.3
-    installManPage foobar.1 delmar.3
+    installManPage \
+        foobar.1 \
+        --name fromsea.3 delmar.3
+  '';
+}
+```
+
+The manpage may be the result of a piped input (e.g. `<(cmd)`), in which
+case the name must be provided before the pipe with the `--name` flag.
+
+```nix
+{
+  nativeBuildInputs = [ installShellFiles ];
+
+  postInstall = ''
+    installManPage --name foobar.1 <($out/bin/foobar --manpage)
+  '';
+}
+```
+
+If no parsing of arguments is desired, pass `--` to opt-out of all subsequent
+arguments.
+
+```nix
+{
+  nativeBuildInputs = [ installShellFiles ];
+
+  # Installs a manpage from a file called "--name"
+  postInstall = ''
+    installManPage -- --name
   '';
 }
 ```

doc/release-notes/rl-2511.section.md

@@ -16,6 +16,8 @@
 
 - The `offrss` package was removed due to lack of upstream maintenance since 2012. It's recommended for users to migrate to another RSS reader
 
+- `installShellFiles`: Allow installManPage to take a piped input, add the `--name` flag for renaming the file when installed. Can also append `--` to opt-out of all subsequent parsing.
+
 - `base16-builder` node package has been removed due to lack of upstream maintenance.
 - `gentium` package now provides `Gentium-*.ttf` files, and not `GentiumPlus-*.ttf` files like before. The font identifiers `Gentium Plus*` are available in the `gentium-plus` package, and if you want to use the more recently updated package `gentium` [by sil](https://software.sil.org/gentium/), you should update your configuration files to use the `Gentium` font identifier.
 - `space-orbit` package has been removed due to lack of upstream maintenance. Debian upstream stopped tracking it in 2011.