Skip to content

Commit 03dea00

Browse files
authored
Refactor headings (#2028)
1 parent 67c9180 commit 03dea00

File tree

2 files changed

+16
-13
lines changed

2 files changed

+16
-13
lines changed

Readme.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -327,7 +327,7 @@ add cheese type mozzarella
327327
Options with an optional option-argument are not greedy and will ignore arguments starting with a dash.
328328
So `id` behaves as a boolean option for `--id -5`, but you can use a combined form if needed like `--id=-5`.
329329

330-
For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).
330+
For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-in-depth.md).
331331

332332
### Required option
333333

@@ -379,7 +379,7 @@ Options: { number: [ '1', '2', '3' ], letter: true }
379379
Remaining arguments: [ 'operand' ]
380380
```
381381

382-
For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).
382+
For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-in-depth.md).
383383

384384
### Version option
385385

@@ -1131,7 +1131,7 @@ program
11311131
There is more information available about:
11321132

11331133
- [deprecated](./docs/deprecated.md) features still supported for backwards compatibility
1134-
- [options taking varying arguments](./docs/options-taking-varying-arguments.md)
1134+
- [options taking varying arguments](./docs/options-in-depth.md)
11351135
- [parsing life cycle and hooks](./docs/parsing-and-hooks.md)
11361136

11371137
## Support

docs/options-taking-varying-arguments.md renamed to docs/options-in-depth.md

+13-10
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
# Options taking varying numbers of option-arguments
1+
<!-- omit from toc -->
2+
# Options in Depth
23

34
The README covers declaring and using options, and mostly parsing will work the way you and your users expect. This page covers some special cases
45
and subtle issues in depth.
@@ -8,8 +9,10 @@ and subtle issues in depth.
89
- [Alternative: Make `--` part of your syntax](#alternative-make-----part-of-your-syntax)
910
- [Alternative: Put options last](#alternative-put-options-last)
1011
- [Alternative: Use options instead of command-arguments](#alternative-use-options-instead-of-command-arguments)
11-
- [Combining short options, and options taking arguments](#combining-short-options-and-options-taking-arguments)
12-
- [Combining short options as if boolean](#combining-short-options-as-if-boolean)
12+
- [Combining short options, and options taking arguments](#combining-short-options-and-options-taking-arguments)
13+
- [Combining short options as if boolean](#combining-short-options-as-if-boolean)
14+
15+
## Options taking varying numbers of option-arguments
1316

1417
Certain options take a varying number of arguments:
1518

@@ -20,11 +23,11 @@ program
2023
.option('--test [name...]') // 0 or more
2124
```
2225

23-
This page uses examples with options taking 0 or 1 arguments, but the discussions also apply to variadic options taking more arguments.
26+
This section uses examples with options taking 0 or 1 arguments, but the discussions also apply to variadic options taking more arguments.
2427

2528
For information about terms used in this document see: [terminology](./terminology.md)
2629

27-
## Parsing ambiguity
30+
### Parsing ambiguity
2831

2932
There is a potential downside to be aware of. If a command has both
3033
command-arguments and options with varying option-arguments, this introduces a parsing ambiguity which may affect the user of your program.
@@ -73,7 +76,7 @@ ingredient: cheese
7376

7477
If you want to avoid your users needing to learn when to use `--`, there are a few approaches you could take.
7578

76-
### Alternative: Make `--` part of your syntax
79+
#### Alternative: Make `--` part of your syntax
7780

7881
Rather than trying to teach your users what `--` does, you could just make it part of your syntax.
7982

@@ -98,7 +101,7 @@ technique: scrambled
98101
ingredient: cheese
99102
```
100103

101-
### Alternative: Put options last
104+
#### Alternative: Put options last
102105

103106
Commander follows the GNU convention for parsing and allows options before or after the command-arguments, or intermingled.
104107
So by putting the options last, the command-arguments do not get confused with the option-arguments.
@@ -120,7 +123,7 @@ technique: scrambled
120123
ingredient: cheese
121124
```
122125

123-
### Alternative: Use options instead of command-arguments
126+
#### Alternative: Use options instead of command-arguments
124127

125128
This is a bit more radical, but completely avoids the parsing ambiguity!
126129

@@ -178,7 +181,7 @@ halal servings: v
178181

179182
If you wish to use options taking varying arguments as boolean options, you need to specify them separately.
180183

181-
```
184+
```console
182185
$ collect -a -v -l
183186
any servings: true
184187
vegan servings: true
@@ -190,7 +193,7 @@ halal servings: true
190193
Before Commander v5, combining a short option and the value was not supported, and combined short flags were always expanded.
191194
So `-avl` expanded to `-a -v -l`.
192195

193-
If you want backwards compatible behaviour, or prefer combining short options as booleans to combining short option and value,
196+
If you want backwards compatible behaviour, or prefer combining short options as booleans to combining short option and value,
194197
you may change the behavior.
195198

196199
To modify the parsing of options taking an optional value:

0 commit comments

Comments
 (0)