-
-
Notifications
You must be signed in to change notification settings - Fork 4.1k
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: document use of POSIX-compliant shell syntax in subdirectory common
#12894
base: main
Are you sure you want to change the base?
Changes from all commits
37bc9fe
5737594
ce7efd7
8c38cae
bbed878
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
@@ -364,7 +364,7 @@ | |||||||||||||||||||||||
Short option mnemonics are optional hints which 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: | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
`slmgr.vbs /dti` | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
|
@@ -376,11 +376,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 379 in contributing-guides/style-guide.md GitHub Actions / build
|
||||||||||||||||||||||||
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 383 in contributing-guides/style-guide.md GitHub Actions / build
|
||||||||||||||||||||||||
|
||||||||||||||||||||||||
- 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. | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
|
@@ -390,6 +390,26 @@ | |||||||||||||||||||||||
|
||||||||||||||||||||||||
## Example commands | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
### POSIX-compliant syntax | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
- The examples of pages in the subdirectory `common` for UNIX-like operating systems (e.g. `pages/common/tar.md`), preferably, should be written with the shell syntax specified by the [latest POSIX standard](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18). | ||||||||||||||||||||||||
tricantivu marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||||||||
However, if you believe the example is hard to read, has little to no use, or is impossible to write in POSIX-compliant syntax, use non-POSIX syntax and add a note or warning indicating it and some or all of its consequences concisely and specifically. For example: | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
```md | ||||||||||||||||||||||||
# IFS | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
> IFS (Internal Field Separator) is a special environment variable that defines the delimiter used for word splitting in Unix shells. | ||||||||||||||||||||||||
> The default value of IFS is a space, tab, and newline. The three characters serve as delimiters. | ||||||||||||||||||||||||
> Note: Not all shells support ANSI C quoted strings (i.e., $'...' and $"..."), the dollar sign could be included in the string. | ||||||||||||||||||||||||
> More information: <https://www.gnu.org/software/bash/manual/html_node/Word-Splitting.html>. | ||||||||||||||||||||||||
``` | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
To help you decide using POSIX-compliant syntax, ask yourself this: | ||||||||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not sure about the wording of this section, maybe we can reword it a bit. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||||
|
||||||||||||||||||||||||
- Is the example too long (i.e. [exceeds the maximum line length](https://github.com/tldr-pages/tldr/blob/main/.markdownlint.json#L5))? | ||||||||||||||||||||||||
- Does the example utilize any [risky](https://unix.stackexchange.com/a/278439) or [inefficient](https://unix.stackexchange.com/a/169765) commands? | ||||||||||||||||||||||||
- Does the example return the correct output? | ||||||||||||||||||||||||
Comment on lines
+407
to
+411
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
How about this? @kbdharun @sebastiaanspeck @tricantivu There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. IMO questions makes things a bit too open and a bit confusing (a positive answer means that I should use POSIX-compliant syntax or not?) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Perhaps I could replace the questions for a guide explaining how to check POSIX-compliance (e.g. |
||||||||||||||||||||||||
|
||||||||||||||||||||||||
### Option syntax | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
- For commonly/frequently used commands (e.g. `grep`, `tar`, `etc`), we prefer using short options along with [mnemonics](#short-option-mnemonics) or both inside a placeholder. | ||||||||||||||||||||||||
|
@@ -550,7 +570,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 573 in contributing-guides/style-guide.md GitHub Actions / build
|
||||||||||||||||||||||||
| 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. | | ||||||||||||||||||||||||
|
@@ -571,7 +591,7 @@ | |||||||||||||||||||||||
|
||||||||||||||||||||||||
Add detailed contexts to remove ambiguity (notice the highlighted word): | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
> Muat konfigurasi dari file yang ditentukan setelah **pengguna** memuat ulang **sistem operasi** | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
Similarly, for the word `start` / `mulai` | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why do lines 398-411 have an extra space at the start of each line?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Editing mistake