From ec4a9a4ee60700decb2d78c7361a43c238bb22f6 Mon Sep 17 00:00:00 2001 From: Janek <27jf@pm.me> Date: Sun, 12 Sep 2021 16:01:45 +0200 Subject: [PATCH] style-guide: put token guidelines into sections & add varargs (#6200) --- contributing-guides/style-guide.md | 76 ++++++++++++++++++------------ 1 file changed, 47 insertions(+), 29 deletions(-) diff --git a/contributing-guides/style-guide.md b/contributing-guides/style-guide.md index d2a7d50366..d387307316 100644 --- a/contributing-guides/style-guide.md +++ b/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, - ex. `{{source_file}}` or `{{wallet.txt}}`. -2. Use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for multi-word tokens. -3. Use `{{filename}}` rather than `{{file_name}}`. -4. For any reference to paths to files or directories, use the format `{{path/to/}}`. - For example, `ln -s {{path/to/file}} {{path/to/symlink}}`. - In case of a possible reference both to a file or a directory, use `{{path/to/file_or_directory}}` -5. Follow the `{{path/to/}}` convention for all path-related commands, except when the - file location is implicit. -6. If a command expects the file to have a particular extension, use 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; - But in a command like `wc -l {{file}}`, using `{{file}}` (without extension) is sufficient. -7. If the example is clearer with an actual value rather than a generic placeholder, use the actual value. - For example, use `iostat {{2}}` rather than `iostat {{interval_in_secs}}`. -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. - 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`. +### Naming +- Use short but descriptive tokens, + such as `{{source_file}}` or `{{wallet.txt}}`. +- Use [`snake_case`](https://wikipedia.org/wiki/snake_case) for multi-word tokens. +- Use an actual value rather than a generic placeholder where appropriate. + For example, use `iostat {{2}}` rather than `iostat {{interval_in_secs}}`. + +### Paths +- Use `{{filename}}` rather than `{{file_name}}`. +- For any reference to paths of files or directories, + use the format `{{path/to/}}`, + except when the location is implicit. +- When the path cannot be relative, + but has to start at the root of the filesystem, + prefix it with a slash, + such as `get {{/path/to/remote_file}}`. +- In case of a possible reference both to a file or a directory, + use `{{path/to/file_or_directory}}`. + +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`. -2. Extensions, ex. `.dll`. -3. Commands, ex. `ls`. +- Paths, ex. `package.json`, `/etc/package.json`. +- Extensions, ex. `.dll`. +- 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 the serial comma is ommitted, it can create ambiguity. +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, +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. @@ -116,4 +134,4 @@ The following guidelines are applied to Chinese (zh) and traditional Chinese (zh In order to maintain readability and normalization, please comply the 6 rules above as much as possible when translating pages into Chinese. -For more information and examples of Chinese-specific rules, check out [*Chinese Copywriting Guidelines*](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.en-US.md). \ No newline at end of file +For more information and examples of Chinese-specific rules, check out [*Chinese Copywriting Guidelines*](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.en-US.md).