Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

style-guide: clarify placeholders #15807

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions contributing-guides/style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -383,7 +383,7 @@
Short option mnemonics are optional hints that can be added to help users understand the meaning of these short options. The assigned mnemonics should match with the ones in the command's official documentation (e.g. from `man` or `Get-Help`). For example:

```md
- [d]isplay the ins[t]allation [i]D for the current device. Useful for offline license activation:

Check failure on line 386 in contributing-guides/style-guide.md

View workflow job for this annotation

GitHub Actions / build

isplay ==> display

`slmgr.vbs /dti`

Expand All @@ -395,11 +395,11 @@
Note that, in the first example, the `[d]`, `[t]`, and `[i]` characters are enclosed with square brackets to indicate that the `/dti` option of the command is a combination of "display", "installation", and "ID", respectively.
Group consecutive mnemonic characters under the same square brackets, for example: `e[xp]i[r]ation` instead of `e[x][p]i[r]ation`.

**Mnemonic characters must be written in a case-sensitive manner**, even when it is placed as the first character of the sentence (i.e. use `[d]isplay` instead of `[D]isplay`).

Check failure on line 398 in contributing-guides/style-guide.md

View workflow job for this annotation

GitHub Actions / build

isplay ==> display

Check failure on line 398 in contributing-guides/style-guide.md

View workflow job for this annotation

GitHub Actions / build

isplay ==> display
This is to avoid conflicts with GNU-style command options which may interpret uppercase options differently than the lowercase ones, such as `-v` for displaying the command's `[v]ersion` number and `-V` to run the command in `[V]erbose` mode.

Option mnemonics may also be used in translations as long as the highlighted word contains similar meanings to the language (commonly English) which the command is written for.
For example, `[d]ownload` in English may be translated into `[d]escargar` in Spanish, `[i]nstall` in English may be translated to `[i]nstallieren` in German, and `[a]pp` in English may be translated into `[a]plikasi` in Indonesian and Malay.

Check failure on line 402 in contributing-guides/style-guide.md

View workflow job for this annotation

GitHub Actions / build

ownload ==> download, own load

Check failure on line 402 in contributing-guides/style-guide.md

View workflow job for this annotation

GitHub Actions / build

nstall ==> install

- Optionally, mnemonics and their enclosed terms can be separated with brackets from the rest of the description (i.e. `([a]ll)`) in translations and specific pages to provide additional context or mention a word not present in the description.

Expand Down Expand Up @@ -468,19 +468,17 @@

- If a command can optionally take 1 or more arguments of the same kind, use an ellipsis: `{{placeholder1 placeholder2 ...}}`.
For instance, if multiple paths are expected, use `{{path/to/directory1 path/to/directory2 ...}}`.
- If a command can optionally take 1 or more arguments of different kinds, use an ellipsis: `{{placeholder1|placeholder2|...}}`.
If there are more than 5 possible values, you can use `|...` after the last item.
- It's impossible to restrict the minimum or (and) maximum placeholder count via `ellipsis`.

It's up to the program to decide how to handle duplicating values, provided syntax
tells no info about whether items are mutually exclusive or not.
- If only one of the multiple options is possible, write it as: `{{placeholder1|placeholder2|placeholder3}}`. If there are more than 4 possible values, you can use `|...` after the last item.

#### Optional placeholders

When documenting optional placeholders like paths or file extensions, it is suggested to specify them in the page or example descriptions instead of the placeholder itself. For example:

- Use `{{path/to/source.ext}}` instead of `{{path/to/source.tar[.gz|.bz2|.xz]}}`.

> [!NOTE]\
> Angle brackets `[]` must always be a substring of the placeholder to not get mixed up with an option placeholder.

### Help and version commands

- We generally put, **in this order**, the help and version commands as the **last two** examples of the page to highlight more practical commands at the beginning of the page. They can be replaced to accommodate other useful examples if required.
Expand Down Expand Up @@ -524,11 +522,11 @@
- 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.

Check failure on line 525 in contributing-guides/style-guide.md

View workflow job for this annotation

GitHub Actions / build

punctuations ==> punctuation, punctuation's

- For example, use `开启 shell,进入交互模式` rather than `开启 shell ,进入交互模式`

4. Use full-width punctuations except for long Latin clauses.

Check failure on line 529 in contributing-guides/style-guide.md

View workflow job for this annotation

GitHub Actions / build

punctuations ==> punctuation, punctuation's

- For example, use `嗨,你好。` rather than `嗨, 你好.`

Expand Down Expand Up @@ -588,7 +586,7 @@
| Image (as means of storage, such as CD, ISO, and Docker) | Image | Another recommended word, [`citra`](https://kbbi.kemdikbud.go.id/entri/citra), is not officially recognized for computing. |
| Initialize, Reinitialize | Inisialisasikan, Inisialisasikan Ulang | The word [`inisialisasi`](https://kbbi.kemdikbud.go.id/entri/inisialisasi) is officially considered as noun. Requires a `-kan` suffix to convert into a verb. |
| Interpreter | Interpreter | Preferred over [`penerjemah`](https://kbbi.kemdikbud.go.id/entri/penerjemah) which is also commonly used to describe `translator`. |
| Install, Reinstall | Pasang, Pasang Ulang | Preferred over `instal` [which is not considered a standard word](https://kbbi.kemdikbud.go.id/entri/instal). |

Check failure on line 589 in contributing-guides/style-guide.md

View workflow job for this annotation

GitHub Actions / build

instal ==> install

Check failure on line 589 in contributing-guides/style-guide.md

View workflow job for this annotation

GitHub Actions / build

instal ==> install
| Load, Reload | Muat, Muat ulang | These words are the same for `boot` and `reboot`. See notes in the bottom section. |
| Options / Preferences (macOS) / Settings | Pengaturan | Preferred over [`opsi`](https://kbbi.kemdikbud.go.id/entri/opsi). |
| Server | Server | Preferred over [`peladen`](https://kbbi.kemdikbud.go.id/entri/peladen) or [`pelayan`](https://kbbi.kemdikbud.go.id/entri/pelayan), which are less common when used in computing contexts. |
Expand All @@ -609,7 +607,7 @@

Add detailed contexts to remove ambiguity (notice the highlighted word):

> Muat konfigurasi dari file yang ditentukan setelah **pengguna** memuat ulang **sistem operasi**

Check failure on line 610 in contributing-guides/style-guide.md

View workflow job for this annotation

GitHub Actions / build

sistem ==> system

Similarly, for the word `start` / `mulai`

Expand Down