style-guide: put token guidelines into sections & add varargs (#6200)

contributing-guides/style-guide.md

@@ -32,7 +32,7 @@ tldrl -f {{page.md}}
 ```
 
 For other ways to use `tldrl`, such as linting an entire directory, check out (what else!)
-[`tldr tldrl`](https://github.com/tldr-pages/tldr/blob/main/pages/common/tldrl.md)
+[`tldr tldrl`](https://github.com/tldr-pages/tldr/blob/main/pages/common/tldrl.md).
 
 Your client may be able to preview a page locally using the `--render` flag:
 
@@ -47,47 +47,65 @@ in order to allow `tldr` clients to highlight them.
 
 Keep the following guidelines in mind when choosing tokens:
 
-1. Use short but descriptive tokens,
+### Naming
-   ex. `{{source_file}}` or `{{wallet.txt}}`.
+- Use short but descriptive tokens,
-2. Use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for multi-word tokens.
+  such as `{{source_file}}` or `{{wallet.txt}}`.
-3. Use `{{filename}}` rather than `{{file_name}}`.
+- Use [`snake_case`](https://wikipedia.org/wiki/snake_case) for multi-word tokens.
-4. For any reference to paths to files or directories, use the format `{{path/to/<placeholder>}}`.
+- Use an actual value rather than a generic placeholder where appropriate.
-   For example, `ln -s {{path/to/file}} {{path/to/symlink}}`.
+  For example, use `iostat {{2}}` rather than `iostat {{interval_in_secs}}`.
-   In case of a possible reference both to a file or a directory, use `{{path/to/file_or_directory}}`
+
-5. Follow the `{{path/to/<placeholder>}}` convention for all path-related commands, except when the
+### Paths
-   file location is implicit.
+- Use `{{filename}}` rather than `{{file_name}}`.
-6. If a command expects the file to have a particular extension, use it.
+- For any reference to paths of files or directories,
-   For example, `unrar x {{compressed.rar}}`.
+  use the format `{{path/to/<placeholder>}}`,
-   In case a generic extension is needed, use `{{.ext}}`, but **only** if an extension is required.
+  except when the location is implicit.
-   For instance, in find.md's example "Find files by extension" (`find {{root_path}} -name '{{*.ext}}'`)
+- When the path cannot be relative,
-   using `{{*.ext}}` explains the command without being unnecessarily specific;
+  but has to start at the root of the filesystem,
-   But in a command like `wc -l {{file}}`, using `{{file}}` (without extension) is sufficient.
+  prefix it with a slash,
-7. If the example is clearer with an actual value rather than a generic placeholder, use the actual value.
+  such as `get {{/path/to/remote_file}}`.
-   For example, use `iostat {{2}}` rather than `iostat {{interval_in_secs}}`.
+- In case of a possible reference both to a file or a directory,
-8. If a command performs irreversible changes to a file system or to user's devices, then write every example in a way that they cannot be unmindfully copy-pasted by the user.
+  use `{{path/to/file_or_directory}}`.
-   For example, instead of `ddrescue --force --no-scrape /dev/sda /dev/sdb` write `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}` and use the `{{/dev/sdXY}}` placeholder for *block devices* instead of `/dev/sda1`.
+
+Extensions
+
+- If a particular extension is expected for the file, append it.
+  For example, `unrar x {{compressed.rar}}`.
+- In case a generic extension is needed, use `{{.ext}}`, but **only** if an extension is required.
+  For instance, in `find.md`'s example "Find files by extension" (`find {{root_path}} -name '{{*.ext}}'`)
+  using `{{*.ext}}` explains the command without being unnecessarily specific;
+  while in `wc -l {{file}}` using `{{file}}` (without extension) is sufficient.
+
+### Special cases
+- If a command performs irreversible changes to a file system or devices,
+  write every example in a way that they cannot be thoughtlessly copy-pasted.
+  For example, instead of `ddrescue --force --no-scrape /dev/sda /dev/sdb`
+  write `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}`
+  and use the `{{/dev/sdXY}}` placeholder for *block devices* instead of `/dev/sda1`.
+- If a command can take a variable number of arguments, use an ellipsis: `{{arg1 arg2 ...}}`
+  If one of multiple options is possible, write it as `{{either|or}}`.
 
 In general, tokens should make it as intuitive as possible
 to figure out how to use the command and fill it in with values.
 
-More technical wording on description lines should use the `backtick` syntax.
+Technical wording on description lines should use the `backtick` syntax.
 Use backticks on the following:
 
-1. Paths, ex. `package.json`, `/etc/package.json`.
+- Paths, ex. `package.json`, `/etc/package.json`.
-2. Extensions, ex. `.dll`.
+- Extensions, ex. `.dll`.
-3. Commands, ex. `ls`.
+- Commands, ex. `ls`.
 
 ## Serial Comma
 
-When declaring a list of 3 or more items, use a [serial comma](https://en.wikipedia.org/wiki/Serial_comma), also known as the Oxford comma.
+When declaring a list of 3 or more items,
-
+use a [serial comma](https://en.wikipedia.org/wiki/Serial_comma),
-When the serial comma is ommitted, it can create ambiguity.
+also known as the Oxford comma,
+since omitting it can create ambiguity.
 
 > Delete the Git branches, tags and remotes.
 
 The example above does not use a serial comma, so this could mean one of two things:
 * Delete the Git branches named `tags` and `remotes`.
-* Delete all of the following, Git branches, Git tags, and Git remotes.
+* Delete all of the following: Git branches, Git tags, and Git remotes.
 
 This can be resolved by inserting a comma before the "and" or "or" in the final element in the list.