Merge pull request #10935 from fricklerhandwerk/cli-docs-formatting

use separate paragraphs inside list items

doc/manual/src/command-ref/nix-build.md

@@ -55,20 +55,20 @@ All options not listed here are passed to
 [`nix-store --realise`](nix-store/realise.md),
 except for `--arg` and `--attr` / `-A` which are passed to [`nix-instantiate`](nix-instantiate.md).
 
-  - <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
+- <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
 
-    Do not create a symlink to the output path. Note that as a result
-    the output does not become a root of the garbage collector, and so
-    might be deleted by `nix-store --gc`.
+  Do not create a symlink to the output path. Note that as a result
+  the output does not become a root of the garbage collector, and so
+  might be deleted by `nix-store --gc`.
 
-  - <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span>
+- <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span>
 
-    Show what store paths would be built or downloaded.
+  Show what store paths would be built or downloaded.
 
-  - <span id="opt-out-link">[`--out-link`](#opt-out-link)</span> / `-o` *outlink*
+- <span id="opt-out-link">[`--out-link`](#opt-out-link)</span> / `-o` *outlink*
 
-    Change the name of the symlink to the output path created from
-    `result` to *outlink*.
+  Change the name of the symlink to the output path created from
+  `result` to *outlink*.
 
 {{#include ./status-build-failure.md}}
 

doc/manual/src/command-ref/nix-channel.md

@@ -27,40 +27,46 @@ The moving parts of channels are:
 
 This command has the following operations:
 
-  - `--add` *url* \[*name*\]\
-    Add a channel *name* located at *url* to the list of subscribed channels.
-    If *name* is omitted, default to the last component of *url*, with the suffixes `-stable` or `-unstable` removed.
+- `--add` *url* \[*name*\]
 
-    > **Note**
-    >
-    > `--add` does not automatically perform an update.
-    > Use `--update` explicitly.
+  Add a channel *name* located at *url* to the list of subscribed channels.
+  If *name* is omitted, default to the last component of *url*, with the suffixes `-stable` or `-unstable` removed.
 
-    A channel URL must point to a directory containing a file `nixexprs.tar.gz`.
-    At the top level, that tarball must contain a single directory with a `default.nix` file that serves as the channel’s entry point.
+  > **Note**
+  >
+  > `--add` does not automatically perform an update.
+  > Use `--update` explicitly.
 
-  - `--remove` *name*\
-    Remove the channel *name* from the list of subscribed channels.
+  A channel URL must point to a directory containing a file `nixexprs.tar.gz`.
+  At the top level, that tarball must contain a single directory with a `default.nix` file that serves as the channel’s entry point.
 
-  - `--list`\
-    Print the names and URLs of all subscribed channels on standard output.
+- `--remove` *name*
 
-  - `--update` \[*names*…\]\
-    Download the Nix expressions of subscribed channels and create a new generation.
-    Update all channels if none is specified, and only those included in *names* otherwise.
+  Remove the channel *name* from the list of subscribed channels.
 
-  - `--list-generations`\
-    Prints a list of all the current existing generations for the
-    channel profile.
+- `--list`
 
-    Works the same way as
-    ```
-    nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations
-    ```
+  Print the names and URLs of all subscribed channels on standard output.
 
-  - `--rollback` \[*generation*\]\
-    Revert channels to the state before the last call to `nix-channel --update`.
-    Optionally, you can specify a specific channel *generation* number to restore.
+- `--update` \[*names*…\]
+
+  Download the Nix expressions of subscribed channels and create a new generation.
+  Update all channels if none is specified, and only those included in *names* otherwise.
+
+- `--list-generations`
+
+  Prints a list of all the current existing generations for the
+  channel profile.
+
+  Works the same way as
+  ```
+  nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations
+  ```
+
+- `--rollback` \[*generation*\]
+
+  Revert channels to the state before the last call to `nix-channel --update`.
+  Optionally, you can specify a specific channel *generation* number to restore.
 
 {{#include ./opt-common.md}}
 

doc/manual/src/command-ref/nix-collect-garbage.md

@@ -48,12 +48,14 @@ Instead, it looks in a few locations, and acts on all profiles it finds there:
 
 These options are for deleting old [profiles] prior to deleting unreachable [store objects].
 
-- <span id="opt-delete-old">[`--delete-old`](#opt-delete-old)</span> / `-d`\
+- <span id="opt-delete-old">[`--delete-old`](#opt-delete-old)</span> / `-d`
+
   Delete all old generations of profiles.
 
   This is the equivalent of invoking [`nix-env --delete-generations old`](@docroot@/command-ref/nix-env/delete-generations.md#generations-old) on each found profile.
 
-- <span id="opt-delete-older-than">[`--delete-older-than`](#opt-delete-older-than)</span> *period*\
+- <span id="opt-delete-older-than">[`--delete-older-than`](#opt-delete-older-than)</span> *period*
+
   Delete all generations of profiles older than the specified amount (except for the generations that were active at that point in time).
   *period* is a value such as `30d`, which would mean 30 days.
 

doc/manual/src/command-ref/nix-copy-closure.md

@@ -27,38 +27,38 @@ When using public key authentication, you can avoid typing the passphrase with `
 
 # Options
 
-  - `--to`
+- `--to`
 
-    Copy the closure of _paths_ from a Nix store accessible from the local machine to the Nix store on the remote _machine_.
-    This is the default behavior.
+  Copy the closure of _paths_ from a Nix store accessible from the local machine to the Nix store on the remote _machine_.
+  This is the default behavior.
 
-  - `--from`
+- `--from`
 
-    Copy the closure of _paths_ from the Nix store on the remote _machine_ to the local machine's specified Nix store.
+  Copy the closure of _paths_ from the Nix store on the remote _machine_ to the local machine's specified Nix store.
 
-  - `--gzip`
+- `--gzip`
 
-    Enable compression of the SSH connection.
+  Enable compression of the SSH connection.
 
-  - `--include-outputs`
+- `--include-outputs`
 
-    Also copy the outputs of [store derivation]s included in the closure.
+  Also copy the outputs of [store derivation]s included in the closure.
 
-    [store derivation]: @docroot@/glossary.md#gloss-store-derivation
+  [store derivation]: @docroot@/glossary.md#gloss-store-derivation
 
-  - `--use-substitutes` / `-s`
+- `--use-substitutes` / `-s`
 
-    Attempt to download missing store objects on the target from [substituters](@docroot@/command-ref/conf-file.md#conf-substituters).
-    Any store objects that cannot be substituted on the target are still copied normally from the source.
-    This is useful, for instance, if the connection between the source and target machine is slow, but the connection between the target machine and `cache.nixos.org` (the default binary cache server) is fast.
+  Attempt to download missing store objects on the target from [substituters](@docroot@/command-ref/conf-file.md#conf-substituters).
+  Any store objects that cannot be substituted on the target are still copied normally from the source.
+  This is useful, for instance, if the connection between the source and target machine is slow, but the connection between the target machine and `cache.nixos.org` (the default binary cache server) is fast.
 
 {{#include ./opt-common.md}}
 
 # Environment variables
 
-  - `NIX_SSHOPTS`
+- `NIX_SSHOPTS`
 
-    Additional options to be passed to `ssh` on the command line.
+  Additional options to be passed to `ssh` on the command line.
 
 {{#include ./env-common.md}}
 

doc/manual/src/command-ref/nix-env/delete-generations.md

@@ -12,7 +12,8 @@ This operation deletes the specified generations of the current profile.
 
 *generations* can be a one of the following:
 
-- <span id="generations-list">[`<number>...`](#generations-list)</span>:\
+- <span id="generations-list">[`<number>...`](#generations-list)</span>
+
   A list of generation numbers, each one a separate command-line argument.
 
   Delete exactly the profile generations given by their generation number.
@@ -30,15 +31,17 @@ This operation deletes the specified generations of the current profile.
   > Because one can roll back to a previous generation, it is possible to have generations newer than the current one.
   > They will also be deleted.
 
-- <span id="generations-time">[`<number>d`](#generations-time)</span>:\
+- <span id="generations-time">[`<number>d`](#generations-time)</span>
+
   The last *number* days
 
   *Example*: `30d`
 
   Delete all generations created more than *number* days ago, except the most recent one of them.
   This allows rolling back to generations that were available within the specified period.
 
-- <span id="generations-count">[`+<number>`](#generations-count)</span>:\
+- <span id="generations-count">[`+<number>`](#generations-count)</span>
+
   The last *number* generations up to the present
 
   *Example*: `+5`

doc/manual/src/command-ref/nix-env/env-common.md

@@ -1,6 +1,7 @@
 # Environment variables
 
-- `NIX_PROFILE`\
+- `NIX_PROFILE`
+
   Location of the Nix profile. Defaults to the target of the symlink
   `~/.nix-profile`, if it exists, or `/nix/var/nix/profiles/default`
   otherwise.