From ee0a2809ead8ff1f68a4d58ac94cc053a51a36db Mon Sep 17 00:00:00 2001 From: Emily Grace Seville Date: Wed, 4 Jan 2023 02:38:49 +1000 Subject: [PATCH] style-guide: refresh page (#9718) * Move `Range syntax` to `Placeholder syntax` chapter * Require generic placeholders when available * Require ranges just for singular arguments * style-guide: update grammar Signed-off-by: K.B.Dharun Krishna * style-guide: update spacing in Chinese-Specific Rules Signed-off-by: K.B.Dharun Krishna * style-guide: fix typos, spacing Signed-off-by: K.B.Dharun Krishna Co-authored-by: K.B.Dharun Krishna --- contributing-guides/style-guide.md | 74 ++++++++++++++++-------------- 1 file changed, 40 insertions(+), 34 deletions(-) diff --git a/contributing-guides/style-guide.md b/contributing-guides/style-guide.md index 17c476dd0..2df0f4f18 100644 --- a/contributing-guides/style-guide.md +++ b/contributing-guides/style-guide.md @@ -102,23 +102,13 @@ Example: `tldr vim` ``` + - Pre-translated alias page templates can be found [here](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md). ## Option syntax - Use GNU-style **long options** (like `--help` rather than `-h`) when they are cross-platform compatible (intended to work the same across multiple platforms). -- In other cases use short options (like `-h`). - -## Range syntax - -All borders of integer and float ranges are included. If you wanna exclude -one border then use incremented or decremented values to do it: -`{{1..5}}` == `[1-6)`. - -- Use `{{from..to}}` syntax for closed ranges. -- Use `{{-infinity..to}}` or `{{from..infinity}}` syntax for integer partially closed ranges. -- Use `{{integer}}` syntax for values where any integer is valid. -- Use `{{float}}` syntax for values where any float is valid. +- In other cases, use short options (like `-h`). ## Placeholder syntax @@ -128,13 +118,28 @@ in order to allow `tldr` clients to highlight them. Keep the following guidelines in mind when choosing placeholders: ### Naming + - Use short but descriptive placeholders, such as `{{path/to/source_file}}` or `{{path/to/wallet.txt}}`. - Use [`snake_case`](https://wikipedia.org/wiki/snake_case) for multi-word placeholders. -- Use an actual value rather than a generic placeholder where appropriate. - For example, use `iostat {{2}}` rather than `iostat {{interval_in_secs}}`. +- Use a generic placeholder rather than an actual value where a generic placeholder is available (but there is an exception to this listed below). For example, use + `iostat {{1..infinity}}` rather than `iostat {{2}}`. + - If there are several consecutive placeholders of the same type + which don't allow adding arbitrary text in them (ranges), then instead of generic placeholders use descriptive ones. For example prefer `input swipe {{x_position}} {{y_position}} {{x_position}} {{y_position}} {{seconds}}` + instead of `input swipe {{-infinity..infinity}} {{-infinity..infinity}} {{-infinity..infinity}} {{-infinity..infinity}} {{1..infinity}}`. + +### Range syntax + +All borders of integer and float ranges get included. If you want to exclude the border, then use incremented or decremented values to do it: +`{{1..5}}` == `[1-6)`. + +- Use `{{from..to}}` syntax for closed ranges. +- Use `{{-infinity..to}}` or `{{from..infinity}}` syntax for integer partially closed ranges. +- Use `{{integer}}` syntax for values where any integer is valid. +- Use `{{float}}` syntax for values where any float is valid. ### Paths + - Use `{{filename}}` when just file name is expected. - For any reference to paths of files or directories, use the format `{{path/to/}}`, @@ -156,8 +161,9 @@ Keep the following guidelines in mind when choosing placeholders: while in `wc -l {{path/to/file}}` using `{{path/to/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 cannot be thoughtlessly copy-pasted. + write every example in a way that cannot be copy pasted thoughtlessly. 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`. @@ -176,13 +182,13 @@ Use backticks on the following: ## Imperative Mood -Example descriptions have to be phrased in imperative mood. -For example, use `List all files`, instead of `Listing all files` or `File listing`. -This also applies to all translations by default, unless otherwise specified in the language-specific section below. +- Example descriptions have to be phrased in imperative mood. +- For example, use `List all files` instead of `Listing all files` or `File listing`. +- This also applies to all translations by default unless otherwise specified in the language-specific section below. ## Serial Comma -When declaring a list of 3 or more items, +- 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. @@ -209,22 +215,22 @@ When not available, use as the default fallback. When Chinese words, Latin words and Arabic numerals are written in the same sentence, more attention must be paid to copywriting. -The following guidelines are applied to Chinese (zh) and traditional Chinese (zh_TW): +The following guidelines are applied to Chinese (`zh`) and traditional Chinese (`zh_TW`) pages: -1. Place one space before/after English words and numbers. - For example, use `列出所有 docker 容器` rather than `列出所有docker容器`. - For example, use `宽度为 50 个字` rather than `宽度为50个字`. -2. Place one space between numbers and units **except** degrees and percentages. - For example, use `容量 50 MB` rather than `容量 50MB`. - For instances of degree and percentage, use `50°C` and `50%` rather than `50 °C` and `50 %`. -3. No additional spaces before/after full-width punctuations. - For example, use `开启 shell，进入交互模式` rather than `开启 shell ，进入交互模式` -4. Use full-width punctuations except for long Latin clauses. - For example, use `嗨，你好。` rather than `嗨, 你好.` -5. Use a half-width punctuation to end a sentence when the last character is half-width. - For example, use `将代码转化为 Python 3.` rather than `将代码转化为 Python 3。` -6. Use precise form for technical terms, and do not use unofficial Chinese abbreviations. - For example, use `Facebook` rather than `facebook`, `fb` or `脸书`. +1. Place one space before/after English words and numbers. + - For example, use `列出所有 docker 容器` rather than `列出所有docker容器`. + - For example, use `宽度为 50 个字` rather than `宽度为50个字`. +2. Place one space between numbers and units **except** degrees and percentages. + - For example, use `容量 50 MB` rather than `容量 50MB`. + - For instances of degree and percentage, use `50°C` and `50%` rather than `50 °C` and `50 %`. +3. No additional spaces before/after full-width punctuations. + - For example, use `开启 shell，进入交互模式` rather than `开启 shell ，进入交互模式` +4. Use full-width punctuations except for long Latin clauses. + - For example, use `嗨，你好。` rather than `嗨, 你好.` +5. Use a half-width punctuation to end a sentence when the last character is half-width. + - For example, use `将代码转化为 Python 3.` rather than `将代码转化为 Python 3。` +6. Use precise form for technical terms, and do not use unofficial Chinese abbreviations. + - For example, use `Facebook` rather than `facebook`, `fb` or `脸书`. In order to maintain readability and normalization, please comply with the 6 rules above as much as possible when translating pages into Chinese.