mirror of
https://github.com/tldr-pages/tldr.git
synced 2025-09-10 15:53:34 +02:00
style-guide: refresh page: move ellipsis to a separate section and extend syntax (#9742)
* Move and reword ellipsis to a separate section * Add notes about grouping placeholders * Permit specifing repetition count for placeholders * Mandate using simplified range syntax for ellipsis * Update contributing-guides/style-guide.md Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com> * Remove redundant note * Refresh repetition syntax for ellipsis * Don't allow restrict repetition count via ellipsis Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
This commit is contained in:
parent
1616fd5544
commit
0284c2390a
1 changed files with 11 additions and 3 deletions
|
@ -160,6 +160,17 @@ All borders of integer and float ranges get included. If you want to exclude the
|
|||
using `{{*.ext}}` explains the command without being unnecessarily specific;
|
||||
while in `wc -l {{path/to/file}}` using `{{path/to/file}}` (without extension) is sufficient.
|
||||
|
||||
### Grouping placeholders
|
||||
|
||||
- If a command can take 0 or more arguments of the same kind, use an ellipsis: `{{placeholder1 placeholder2 ...}}`.
|
||||
For instance, if multiple paths are expected `{{path/to/directory1 path/to/directory2 ...}}` can be used.
|
||||
- If a command can take 0 or more arguments of different kinds, use an ellipsis: `{{placeholder1|placeholder2|...}}`.
|
||||
If there are more than 5 possible values 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.
|
||||
|
||||
### Special cases
|
||||
|
||||
- If a command performs irreversible changes to a file system or devices,
|
||||
|
@ -167,9 +178,6 @@ All borders of integer and float ranges get included. If you want to exclude the
|
|||
For example, instead of `ddrescue --force --no-scrape /dev/sda /dev/sdb`
|
||||
write `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}`
|
||||
and use the `{{/dev/sdXY}}` placeholder for *block devices* instead of `/dev/sda1`.
|
||||
- If a command can take a variable number of arguments, use an ellipsis: `{{arg1 arg2 ...}}`.
|
||||
If one of the multiple options is possible, write it as `{{either|or}}`.
|
||||
If there are more than 5 alternatives, use `|...` for the ellipsis.
|
||||
|
||||
In general, placeholders should make it as intuitive as possible
|
||||
to figure out how to use the command and fill it in with values.
|
||||
|
|
Loading…
Add table
Reference in a new issue