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:
Emily Grace Seville
2023-01-10 11:54:53 +10:00
committed by GitHub
parent 1616fd5544
commit 0284c2390a

View File

@@ -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.