lilith/tldr
1
0
Fork 0
mirror of https://github.com/tldr-pages/tldr.git synced 2025-07-23 21:15:26 +02:00
Code Activity

style-guide: reorder instructions (#15941)

Browse source
This commit is contained in:
Managor 2025-03-15 20:48:18 +02:00 • committed by GitHub
parent 0045929712
commit 0897084ebb
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 23 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
contributing-guides/style-guide.md
View file

@ -291,7 +291,7 @@ This can be resolved by inserting a comma before the "and" or "or" in the final
### Special cases
- If a command performs irreversible changes to a file system or devices,
If a command performs irreversible changes to a file system or devices,
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}}`
@ -300,6 +300,8 @@ This can be resolved by inserting a comma before the "and" or "or" in the final
In general, placeholders should make it as intuitive as possible
to figure out how to use the command and fill it in with values.
Acronym expansions (i.e. protocols, tools, etc) must not be translated unless there is a recognized native equivalent for them.
Technical wording on description lines should use the `backtick` syntax.
Use backticks on the following:
@ -309,8 +311,28 @@ Use backticks on the following:
- Standard streams: `stdout`, `stdin`, `stderr`. **Do not** use the full names (e.g. standard output).
- Compression algorithms, e.g. `zip`, `7z`, `xz`.
When describing keycaps or a keyboard shortcut for a utility, use the same [keypress syntax](#keypress-syntax) as in example commands. Make sure to enclose it in backticks so that it is not invisible in markdown renderers (i.e. ``Print the last lines of a given file and keep reading it until `<Ctrl c>`:``).
## Heading
### Program description
- 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`)
- If the program name differs from its executable name, it can be named at the start of the heading (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`).
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 should instead be simplified to make it easier for everyone to read:
```md
> Change the current working directory.
```
### More information links
- On the `More information` link line, we prefer linking to the author's provided documentation of the command-line reference or the man page. When not available, use <https://manned.org> as the default fallback for all platforms
@ -368,29 +390,6 @@ the part of the address that starts with `?view=`.
## Example descriptions
### Wording
- 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`).
- 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 should instead be simplified to make it easier for everyone to read:
```md
> Change the current working directory.
```
### Formatting
- Proper names should be capitalized in the description whenever applicable (e.g. use `A tool for interacting with a Git repository.` instead of ``A tool for interacting with a `git` repository.``).
- Acronym expansions (i.e. protocols, tools, etc) must not be translated unless there is a recognized native equivalent for them.
- When documenting keycaps or a keyboard shortcut for a utility, use the same [keypress syntax](#keypress-syntax) as in example commands. Make sure to enclose it in backticks so that it is not invisible to markdown renderers (i.e. ``Print the last lines of a given file and keep reading it until `<Ctrl c>`:``).
### Short option mnemonics
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: