mirror of https://github.com/CrimsonTome/tldr.git
style-guide: add guidelines for `--opt arg`, improve wording (#10906)
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).
|
- 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`).
|
- 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
|
## 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.
|
Technical wording on description lines should use the `backtick` syntax.
|
||||||
Use backticks on the following:
|
Use backticks on the following:
|
||||||
|
|
||||||
- Paths, ex. `package.json`, `/etc/package.json`.
|
- Paths, e.g. `package.json`, `/etc/package.json`.
|
||||||
- Extensions, ex. `.dll`.
|
- Extensions, e.g. `.dll`.
|
||||||
- Commands, ex. `ls`.
|
- Commands, e.g. `ls`.
|
||||||
|
|
||||||
## Descriptions
|
## 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 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`).
|
- 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
|
### 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.
|
- 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
|
```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.
|
> `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
|
```md
|
||||||
> Change the current working directory.
|
> 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.
|
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
|
```md
|
||||||
- Listing all files:
|
- Listing all files:
|
||||||
|
@ -213,13 +220,6 @@ Similarly, when writing examples, instead of `Listing all files:`, `List all fil
|
||||||
`ls`
|
`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
|
## Serial Comma
|
||||||
|
|
||||||
- When declaring a list of 3 or more items,
|
- When declaring a list of 3 or more items,
|
||||||
|
|
Loading…
Reference in New Issue