mirror of
https://github.com/tldr-pages/tldr.git
synced 2024-09-21 00:38:17 +03:00
style-guide: add guidelines for --opt arg
, improve wording (#10906)
This commit is contained in:
parent
05ef9b0fde
commit
5afb6ec14e
@ -109,6 +109,7 @@ Example:
|
||||
|
||||
- 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`).
|
||||
- Prefer using a space instead of the equals sign (`=`) to separate options from their arguments (i.e. use `--opt arg` instead of `--opt=arg`), unless the program does not support it.
|
||||
|
||||
## Placeholder syntax
|
||||
|
||||
@ -175,27 +176,26 @@ to figure out how to use the command and fill it in with values.
|
||||
Technical wording on description lines should use the `backtick` syntax.
|
||||
Use backticks on the following:
|
||||
|
||||
- Paths, ex. `package.json`, `/etc/package.json`.
|
||||
- Extensions, ex. `.dll`.
|
||||
- Commands, ex. `ls`.
|
||||
- Paths, e.g. `package.json`, `/etc/package.json`.
|
||||
- Extensions, e.g. `.dll`.
|
||||
- Commands, e.g. `ls`.
|
||||
|
||||
## Descriptions
|
||||
|
||||
|
||||
- Avoid using the page title in the description (e.g. use `A sketching and painting program designed for digital artists` instead of `Krita is a sketching and painting program designed for digital artists`) unless the program name differs from the executable name (e.g. `rg` and Ripgrep).
|
||||
- Avoid mentioning that the program is used on the command-line (e.g. use `Ripgrep is a recursive line-oriented search tool` instead of `Ripgrep is a recursive line-oriented CLI search tool`).
|
||||
|
||||
### Imperative Mood
|
||||
|
||||
- **All descriptions have to be phrased in an imperative mood and must be concise.**
|
||||
- **All descriptions must be concise and phrased in the imperative mood.**
|
||||
- This also applies to all translations by default unless otherwise specified in the language-specific section below.
|
||||
- For example, when writing documentation for `cd`, a tool to check out and work on a specific directory in the Terminal or Command Prompt, **do not** write lengthy descriptions such as:
|
||||
- For example, when writing documentation for `cd`, a tool to check out and work on a specific directory in the Terminal or Command Prompt, **do not** write a lengthy description such as:
|
||||
|
||||
```md
|
||||
> `cd` is a system tool, available in Windows, macOS, and Linux, to check out a specific directory to get things done in the Command Prompt, Terminal, and PowerShell.
|
||||
```
|
||||
|
||||
It can be simplified for everyone to read:
|
||||
It should instead be simplified to make it easier for everyone to read:
|
||||
|
||||
```md
|
||||
> Change the current working directory.
|
||||
@ -205,7 +205,14 @@ If you are afraid the commands may differ between platforms or operating systems
|
||||
|
||||
In this case, the information of the Windows version of `cd` (stored in `pages/windows/cd.md`) will be displayed by default to Windows users, and a generic/common version (stored in `pages/common/cd.md`) will be displayed for Linux, macOS, and other platforms.
|
||||
|
||||
Similarly, when writing examples, instead of `Listing all files:`, `List all files:` can be be used as the example's description below:
|
||||
When writing descriptions for command examples, **check for any grammatical errors**. `Go to the specified directory` is preferred instead of:
|
||||
|
||||
- `Going to the specified directory` (should not be in present participle form)
|
||||
- `This command will go to the specified directory` (it is clear that this example works for *this* comment)
|
||||
- `Let's go to the specified directory!`
|
||||
- `Directory change` (use the active form instead of passive, if possible)
|
||||
|
||||
For instance, instead of `Listing all files:`, `List all files:` can be be used as the example's description below:
|
||||
|
||||
```md
|
||||
- Listing all files:
|
||||
@ -213,13 +220,6 @@ Similarly, when writing examples, instead of `Listing all files:`, `List all fil
|
||||
`ls`
|
||||
```
|
||||
|
||||
When writing descriptions for command examples, **check out for any grammatical errors**. `Go to the specified directory` is preferred instead of:
|
||||
|
||||
- `Going to the specified directory` (should not be in present participle form)
|
||||
- `This command will go to the specified directory` (it is clear that this example works for *this* comment
|
||||
- `Let's go to the specified directory!`
|
||||
- `Directory change` (use active form instead of passive, if possible)
|
||||
|
||||
## Serial Comma
|
||||
|
||||
- When declaring a list of 3 or more items,
|
||||
|
Loading…
Reference in New Issue
Block a user