From e84d9301b83bc33daa5c9cb9cbd0fe4643e8516c Mon Sep 17 00:00:00 2001 From: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com> Date: Tue, 29 Sep 2026 08:13:23 +0200 Subject: [PATCH] pages/*: apply consistent subcommand note, style-guide: update subcommand note (#24274) * pages/*: use consistent format for subcommand documentation notes * gcrane: format command name as code * pages/*: drop "etc." from subcommand notes whose lists are complete * style-guide: document when to use "etc." in subcommand notes --- contributing-guides/style-guide.md | 9 ++++++++- pages/common/bun-pm.md | 2 +- pages/common/cradle.md | 2 +- pages/common/docker-compose.md | 2 +- pages/common/docker.md | 2 +- pages/common/doppler.md | 2 +- pages/common/gcloud.md | 2 +- pages/common/gcrane.md | 2 +- pages/common/jj-config.md | 2 +- pages/common/jj-file.md | 2 +- pages/common/jj-operation.md | 2 +- pages/common/jj-tag.md | 2 +- pages/common/nh.md | 2 +- pages/common/nix-flake.md | 2 +- pages/common/sfdk.md | 2 +- pages/common/uv.md | 2 +- pages/common/wacli.md | 2 +- pages/common/yadm.md | 2 +- pages/linux/apptainer.md | 2 +- pages/linux/b4.md | 2 +- pages/linux/systemctl.md | 2 +- pages/windows/choco.md | 2 +- pages/windows/gethelpcmd.md | 2 +- 23 files changed, 30 insertions(+), 23 deletions(-) diff --git a/contributing-guides/style-guide.md b/contributing-guides/style-guide.md index e653ba4a23..dac6261ae1 100644 --- a/contributing-guides/style-guide.md +++ b/contributing-guides/style-guide.md @@ -303,6 +303,13 @@ When linking pages to websites that have locale settings like the Microsoft Lear > Some subcommands such as `commit`, `add`, `branch`, `switch`, `push`, etc. have their own usage documentation. ``` +- If the listed subcommands are not all the subcommands that have their own page, end the list with `etc.`. If every subcommand with its own page is listed, omit `etc.` and join the last item with `and` instead: + +```md +> Some subcommands such as `append` and `filter` have their own usage documentation. +> Some subcommands such as `delete`, `list`, and `set` have their own usage documentation. +``` + #### Heading order The heading should adhere to the following order: @@ -311,7 +318,7 @@ The heading should adhere to the following order: > Short description of the functionality. > Further clarification of the functionality. > Note: Any note for the usage. -> Some subcommands such as `subcommand1`, `subcommand2` have their own usage documentation. +> Some subcommands such as `subcommand1`, `subcommand2`, etc. have their own usage documentation. > See also: `command`. > More information: . ``` diff --git a/pages/common/bun-pm.md b/pages/common/bun-pm.md index 57e5b1a6f7..0b1204910c 100644 --- a/pages/common/bun-pm.md +++ b/pages/common/bun-pm.md @@ -1,7 +1,7 @@ # bun pm > A set of utilities for working with Bun's package manager. -> Some subcommands such as `pack`, `pkg` have their own usage documentation. +> Some subcommands such as `pack`, `pkg`, etc. have their own usage documentation. > More information: . - Create a tarball of the current workspace: diff --git a/pages/common/cradle.md b/pages/common/cradle.md index 7714c7b6de..1a9123da64 100644 --- a/pages/common/cradle.md +++ b/pages/common/cradle.md @@ -1,7 +1,7 @@ # cradle > The Cradle PHP framework. -> Some subcommands such as `install` and `package` have their own usage documentation. +> Some subcommands such as `install`, `package`, etc. have their own usage documentation. > More information: . - Install Cradle components (prompts for additional info): diff --git a/pages/common/docker-compose.md b/pages/common/docker-compose.md index 970bfdc147..b85053bcee 100644 --- a/pages/common/docker-compose.md +++ b/pages/common/docker-compose.md @@ -1,7 +1,7 @@ # docker compose > Run and manage multi container Docker applications. -> Some subcommands such as `up`, `down`, `logs`, `stop` have their own usage documentation. +> Some subcommands such as `up`, `down`, `logs`, `stop`, etc. have their own usage documentation. > More information: . - List all running containers: diff --git a/pages/common/docker.md b/pages/common/docker.md index 3c33e2be30..7797c8a744 100644 --- a/pages/common/docker.md +++ b/pages/common/docker.md @@ -1,7 +1,7 @@ # docker > Manage Docker containers and images. -> Some subcommands such as `container` and `image` have their own usage documentation. +> Some subcommands such as `container`, `image`, etc. have their own usage documentation. > More information: . - List all Docker containers (running and stopped): diff --git a/pages/common/doppler.md b/pages/common/doppler.md index 55499fbe7a..8ffe210e71 100644 --- a/pages/common/doppler.md +++ b/pages/common/doppler.md @@ -1,7 +1,7 @@ # doppler > Manage environment variables across different environments. -> Some subcommands such as `run` and `secrets` have their own usage documentation. +> Some subcommands such as `run`, `secrets`, etc. have their own usage documentation. > More information: . - Set up Doppler project and configuration in current directory: diff --git a/pages/common/gcloud.md b/pages/common/gcloud.md index 6b9aefa4d1..36a1531cd9 100644 --- a/pages/common/gcloud.md +++ b/pages/common/gcloud.md @@ -1,7 +1,7 @@ # gcloud > The official CLI tool for Google Cloud Platform. -> Some subcommands such as `app` and `init` have their own usage documentation. +> Some subcommands such as `app`, `init`, etc. have their own usage documentation. > More information: . - List all properties in one's active configuration: diff --git a/pages/common/gcrane.md b/pages/common/gcrane.md index a40c806ee2..ad44fc5e41 100644 --- a/pages/common/gcrane.md +++ b/pages/common/gcrane.md @@ -2,7 +2,7 @@ > Container images managing tool. > This tool implements a superset of the `crane` commands, with additional commands that are specific to Google Container Registry (`gcr.io`). -> Some subcommands such as `copy`, `gc`, `help`, `ls` have their own usage documentation. +> Some subcommands such as `copy`, `gc`, `help`, `ls`, etc. have their own usage documentation. > See also: `crane`. > More information: . diff --git a/pages/common/jj-config.md b/pages/common/jj-config.md index 12f5e3bf94..cd84586740 100644 --- a/pages/common/jj-config.md +++ b/pages/common/jj-config.md @@ -1,7 +1,7 @@ # jj config > Manage config options. -> Some subcommands such as `edit`, `get`, `list`, `path`, `set`, `unset` have their own usage documentation. +> Some subcommands such as `edit`, `get`, `list`, `path`, `set`, and `unset` have their own usage documentation. > More information: . - Start an editor on the user-level config file: diff --git a/pages/common/jj-file.md b/pages/common/jj-file.md index cb55135fbe..fcad9ddbc6 100644 --- a/pages/common/jj-file.md +++ b/pages/common/jj-file.md @@ -1,7 +1,7 @@ # jj file > Manage and inspect files in a `jj` repository. -> Some subcommands such as `annotate`, `show`, `track`, `untrack` have their own usage documentation. +> Some subcommands such as `annotate`, `show`, `track`, `untrack`, etc. have their own usage documentation. > More information: . - List files tracked in the working copy: diff --git a/pages/common/jj-operation.md b/pages/common/jj-operation.md index e66a8c1ccc..3bbe557f0a 100644 --- a/pages/common/jj-operation.md +++ b/pages/common/jj-operation.md @@ -1,7 +1,7 @@ # jj operation > Work with the operation log of a `jj` repository. -> Some subcommands such as `abandon`, `diff`, `integrate`, `log`, `restore`, `revert`, `show` have their own usage documentation. +> Some subcommands such as `abandon`, `diff`, `integrate`, `log`, `restore`, `revert`, and `show` have their own usage documentation. > More information: . - Show operation log: diff --git a/pages/common/jj-tag.md b/pages/common/jj-tag.md index cc03cb1d1d..0ecdf6f776 100644 --- a/pages/common/jj-tag.md +++ b/pages/common/jj-tag.md @@ -1,7 +1,7 @@ # jj tag > Manage tags in a `jj` repository. -> Some subcommands such as `delete`, `list`, `set` have their own usage documentation. +> Some subcommands such as `delete`, `list`, and `set` have their own usage documentation. > More information: . - Create a tag pointing to the current working copy revision: diff --git a/pages/common/nh.md b/pages/common/nh.md index 8b1cbf2554..083176821b 100644 --- a/pages/common/nh.md +++ b/pages/common/nh.md @@ -1,7 +1,7 @@ # nh > Modern helper utility tool for the Nix/NixOS ecosystem. -> Some subcommands such as `os`, `home`, `clean`, `search` have their own usage documentation. +> Some subcommands such as `os`, `home`, `clean`, and `search` have their own usage documentation. > More information: . - Build and switch to a specified NixOS flake configuration: diff --git a/pages/common/nix-flake.md b/pages/common/nix-flake.md index eb9247a9fc..1fd4eb4831 100644 --- a/pages/common/nix-flake.md +++ b/pages/common/nix-flake.md @@ -1,7 +1,7 @@ # nix flake > Manage Nix flakes. -> Some subcommands such as `init`, `show`, `info` have their own usage documentation. +> Some subcommands such as `init`, `show`, and `info` have their own usage documentation. > More information: . - Update all inputs (dependencies) of the flake in the current directory: diff --git a/pages/common/sfdk.md b/pages/common/sfdk.md index 9d925f8dde..4cf20f81aa 100644 --- a/pages/common/sfdk.md +++ b/pages/common/sfdk.md @@ -1,7 +1,7 @@ # sfdk > Frontend of the Sailfish SDK. -> Some subcommands such as `init`, `build-init`, `device` have their own usage documentation. +> Some subcommands such as `init`, `build-init`, `device`, etc. have their own usage documentation. > More information: . - Set up the current environment for building for SailfishOS with a specific version and architecture target: diff --git a/pages/common/uv.md b/pages/common/uv.md index 78606a28a3..4545443f27 100644 --- a/pages/common/uv.md +++ b/pages/common/uv.md @@ -1,7 +1,7 @@ # uv > A fast Python package and project manager. -> Some subcommands such as `tool` and `python` have their own usage documentation. +> Some subcommands such as `tool`, `python`, etc. have their own usage documentation. > More information: . - Create a new Python project in the current directory: diff --git a/pages/common/wacli.md b/pages/common/wacli.md index 3c3936ab9d..7f5db929f6 100644 --- a/pages/common/wacli.md +++ b/pages/common/wacli.md @@ -1,7 +1,7 @@ # wacli > WhatsApp command-line client for sending messages, managing chats, and contacts. -> Some subcommands such as `send`, `messages`, `chats`, and `contacts` have their own usage documentation. +> Some subcommands such as `send`, `messages`, `chats`, `contacts`, etc. have their own usage documentation. > More information: . - Authenticate via QR code: diff --git a/pages/common/yadm.md b/pages/common/yadm.md index 4e93ab46b9..d22af9023f 100644 --- a/pages/common/yadm.md +++ b/pages/common/yadm.md @@ -1,7 +1,7 @@ # yadm > A dotfiles manager that works by using `git`. -> Some subcommands such as `init`, `clone`, `push`, and `pull` have their own usage documentation. +> Some subcommands such as `init`, `clone`, `push`, `pull`, etc. have their own usage documentation. > More information: . - Override yadm's configuration directory: diff --git a/pages/linux/apptainer.md b/pages/linux/apptainer.md index 3a2a164896..4cd74557bb 100644 --- a/pages/linux/apptainer.md +++ b/pages/linux/apptainer.md @@ -1,7 +1,7 @@ # apptainer > Manage containers for HPC and scientific computing. -> Some subcommands such as `build`, `pull`, and `push` have their own usage documentation. +> Some subcommands such as `build`, `pull`, `push`, etc. have their own usage documentation. > More information: . - Download a container from Docker Hub: diff --git a/pages/linux/b4.md b/pages/linux/b4.md index 8fa14d2d13..b28f6cfb09 100644 --- a/pages/linux/b4.md +++ b/pages/linux/b4.md @@ -1,7 +1,7 @@ # b4 > A tool for working with patches and pull requests in a public-inbox archive. -> Some subcommands such as `am`, `shazam`, `prep`, `send` have their own usage documentation. +> Some subcommands such as `am`, `shazam`, `prep`, and `send` have their own usage documentation. > More information: . - Retrieve a thread from a public-inbox archive and save as an mbox file: diff --git a/pages/linux/systemctl.md b/pages/linux/systemctl.md index 301d01c1ec..31b3572118 100644 --- a/pages/linux/systemctl.md +++ b/pages/linux/systemctl.md @@ -1,7 +1,7 @@ # systemctl > Control the systemd system and service manager. -> Some subcommands such as `disable`, `status`, `reboot` etc. have their own usage documentation. +> Some subcommands such as `disable`, `status`, `reboot`, etc. have their own usage documentation. > More information: . - Show all running services: diff --git a/pages/windows/choco.md b/pages/windows/choco.md index 0cc68907cd..bfed95ab9c 100644 --- a/pages/windows/choco.md +++ b/pages/windows/choco.md @@ -1,7 +1,7 @@ # choco > The Chocolatey package manager. -> Some subcommands such as `install`, `upgrade`, `pin` have their own usage documentation. +> Some subcommands such as `install`, `upgrade`, `pin`, etc. have their own usage documentation. > More information: . - Install a package: diff --git a/pages/windows/gethelpcmd.md b/pages/windows/gethelpcmd.md index 81a3cc6461..eb840e2e9f 100644 --- a/pages/windows/gethelpcmd.md +++ b/pages/windows/gethelpcmd.md @@ -3,7 +3,7 @@ > Analyze and fix common problems in Microsoft 365 Enterprise installations. > Formerly Microsoft Support and Recovery Assistant (SaRA), command-line version (`SaRAcmd.exe`). > Note: This command is deprecated, use the GUI troubleshooters available within Windows Settings instead. It is not related to PowerShell (`Get-Help`). -> Some subcommands such as `OutlookCalendarCheckTask`, `ExpertExperienceAdminTask` have their own usage documentation. +> Some subcommands such as `OutlookCalendarCheckTask`, `ExpertExperienceAdminTask`, etc. have their own usage documentation. > More information: . - View documentation for PowerShell's `Get-Help` command: