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:

committed by
GitHub

parent
1616fd5544
commit
0284c2390a
@@ -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;
|
using `{{*.ext}}` explains the command without being unnecessarily specific;
|
||||||
while in `wc -l {{path/to/file}}` using `{{path/to/file}}` (without extension) is sufficient.
|
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
|
### 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,
|
||||||
@@ -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`
|
For example, instead of `ddrescue --force --no-scrape /dev/sda /dev/sdb`
|
||||||
write `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}`
|
write `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}`
|
||||||
and use the `{{/dev/sdXY}}` placeholder for *block devices* instead of `/dev/sda1`.
|
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
|
In general, placeholders should make it as intuitive as possible
|
||||||
to figure out how to use the command and fill it in with values.
|
to figure out how to use the command and fill it in with values.
|
||||||
|
Reference in New Issue
Block a user