From 0a822028f4de152402cda0a0be84bd83326c021e Mon Sep 17 00:00:00 2001
From: John Gee <john@ruru.gen.nz>
Date: Mon, 21 Mar 2022 00:16:46 +1300
Subject: [PATCH 1/2] Add more detail about options and option-arguments

---
 Readme.md | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/Readme.md b/Readme.md
index e43bbea82..c13a538b1 100644
--- a/Readme.md
+++ b/Readme.md
@@ -178,8 +178,14 @@ The parsed options can be accessed by calling `.opts()` on a `Command` object, a
 
 Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.
 
-Multiple short flags may optionally be combined in a single argument following the dash: boolean flags, followed by a single option taking a value (possibly followed by the value).
-For example `-a -b -p 80` may be written as `-ab -p80` or even `-abp80`.
+An option and its option-argument can be separated by a space, or combined into the same argument. The option-argument can follow the short option directly or follow an `=` for a long option.
+
+```bash
+serve -p 80
+serve -p80
+serve --port 80
+serve --port=80
+```
 
 You can use `--` to indicate the end of the options, and any remaining arguments will be used without being interpreted.
 
@@ -226,6 +232,9 @@ pizza details:
 - cheese
 ```
 
+Multiple boolean short options may be combined together following the dash, and may be followed by a single short option taking a value.
+For example `-d -s -p cheese` may be written as `-ds -p cheese` or even `-dsp cheese`.
+
 `program.parse(arguments)` processes the arguments, leaving any args not consumed by the program options in the `program.args` array. The parameter is optional and defaults to `process.argv`.
 
 ### Default option value
@@ -310,6 +319,9 @@ $ pizza-options --cheese mozzarella
 add cheese type mozzarella
 ```
 
+A space-separated argument is only consumed by an optional
+if it does not start with a dash. So `id` behaves as a boolean option for `--id -5`, but you can use a combined form if needed like `--id=-5`.
+
 For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).
 
 ### Required option

From b261d3e243e05ed5cc9bc4cf68862649889310b4 Mon Sep 17 00:00:00 2001
From: John Gee <john@ruru.gen.nz>
Date: Mon, 21 Mar 2022 00:34:09 +1300
Subject: [PATCH 2/2] Use "greedy" in description

---
 Readme.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Readme.md b/Readme.md
index c13a538b1..fa173e53e 100644
--- a/Readme.md
+++ b/Readme.md
@@ -235,6 +235,9 @@ pizza details:
 Multiple boolean short options may be combined together following the dash, and may be followed by a single short option taking a value.
 For example `-d -s -p cheese` may be written as `-ds -p cheese` or even `-dsp cheese`.
 
+Options with an expected option-argument are greedy and will consume the following argument whatever the value.
+So `--id -xyz` reads `-xyz` as the option-argument.
+
 `program.parse(arguments)` processes the arguments, leaving any args not consumed by the program options in the `program.args` array. The parameter is optional and defaults to `process.argv`.
 
 ### Default option value
@@ -319,8 +322,8 @@ $ pizza-options --cheese mozzarella
 add cheese type mozzarella
 ```
 
-A space-separated argument is only consumed by an optional
-if it does not start with a dash. So `id` behaves as a boolean option for `--id -5`, but you can use a combined form if needed like `--id=-5`.
+Options with an optional option-argument are not greedy and will ignore arguments starting with a dash.
+So `id` behaves as a boolean option for `--id -5`, but you can use a combined form if needed like `--id=-5`.
 
 For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).