From 94eeb4423fb0a947eb0a5b7d04494d12448c2dfd Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 12:25:09 +0200
Subject: [PATCH 01/30] adjust to two heading levels

---
 doc/upgrade-breakage.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 7625d3f262..f048ec3198 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -138,16 +138,20 @@ instead.
 
 (Option `simple_word_eval` is part of group `oil:upgrade`.)
 
-## More Quotes May Be Needed
+## Rare strings parsed, if not quoted
 
-### With `oil:upgrade` Options
+### '@foo' as argument (parse_at)
 
 Option `parse_at`.  In Oil, `@` is used to splice arrays.  To pass a string
 `@foo` to a command, quote it like `'@foo'`.
 
+### '{' as argument (parse_brace)
+
 Option `parse_brace`.  Braces after commands start block arguments.  To change
 to a directory named `{`, quote it like `cd '{'`.
 
+### '=foo' as first-word or argument (parse_equals)
+
 Option `parse_equals`.  A statement like `x = 42` is a "bare assignment" or
 attribute.  To pass `=` to a command `x`, quote it like `x '='`.
 

From fa91fde984cf947ecf18656658089542b06ee75d Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 12:51:02 +0200
Subject: [PATCH 02/30] list first-words first (and within heading level)

---
 doc/upgrade-breakage.md | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index f048ec3198..5c71d8c5f0 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -115,9 +115,9 @@ Instead, write `'rfoo'` if that's what you mean.
 
 (Option `parse_raw_string` is part of group `oil:upgrade`.)
 
-## Unsupported
+## Unsupported Syntax
 
-### Extended Globs in Word Evaluation
+### No Extended Globs in Word Evaluation
 
 Like regular globs, the extended glob syntax is used in two ways:
 
@@ -138,32 +138,37 @@ instead.
 
 (Option `simple_word_eval` is part of group `oil:upgrade`.)
 
-## Rare strings parsed, if not quoted
+## New Strings Parsed, if not quoted (rarely a problem)
 
-### '@foo' as argument (parse_at)
+### New first-word keywords (e.g. `proc`, `const`, `var`, `setvar`)
+
+Oil has new keywords like `proc`, `const`, `var`, and `setvar`.  To use them
+as command names, quote them like `'proc'`.
+
+### `=foo` as first-word, is too similar to `= foo`
+
+To avoid confusion with Oil's `=` operator, a word like `=foo` can't be the first word in a command.
+To invoke such commands, quote them like `'=x'`.
+
+There is very little reason to use commands like `'proc'` an, `'=x'`, so you
+will likely never run into this!
+
+### `@foo` as argument (parse_at)
 
 Option `parse_at`.  In Oil, `@` is used to splice arrays.  To pass a string
 `@foo` to a command, quote it like `'@foo'`.
 
-### '{' as argument (parse_brace)
+### `{` as argument (parse_brace)
 
 Option `parse_brace`.  Braces after commands start block arguments.  To change
 to a directory named `{`, quote it like `cd '{'`.
 
-### '=foo' as first-word or argument (parse_equals)
+### `=foo` as argument (parse_equals)
 
 Option `parse_equals`.  A statement like `x = 42` is a "bare assignment" or
 attribute.  To pass `=` to a command `x`, quote it like `x '='`.
 
-### Unconditionally
 
-- To avoid confusion with Oil's `=` operator, a word like `=x` can't be the first word in a command.
-  To invoke such commands, quote them like `'=x'`.
-- Oil has new keywords like `proc`, `const`, `var`, and `setvar`.  To use them
-  as command names, quote them like `'proc'`.
-
-There is very little reason to use commands like `'=x'` and `'proc'`, so you
-will likely never run into this!
 
 ## Summary
 

From 5e74fd694e53fe7cad74e89aa59e93faea47716c Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 12:57:52 +0200
Subject: [PATCH 03/30] improve headings

---
 doc/upgrade-breakage.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 5c71d8c5f0..85b0cea8a1 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -138,7 +138,7 @@ instead.
 
 (Option `simple_word_eval` is part of group `oil:upgrade`.)
 
-## New Strings Parsed, if not quoted (rarely a problem)
+## Some Strings Now Parsed, if not quoted (rarely a problem)
 
 ### New first-word keywords (e.g. `proc`, `const`, `var`, `setvar`)
 
@@ -153,17 +153,17 @@ To invoke such commands, quote them like `'=x'`.
 There is very little reason to use commands like `'proc'` an, `'=x'`, so you
 will likely never run into this!
 
-### `@foo` as argument (parse_at)
+### `@foo` as argument (splices)
 
 Option `parse_at`.  In Oil, `@` is used to splice arrays.  To pass a string
 `@foo` to a command, quote it like `'@foo'`.
 
-### `{` as argument (parse_brace)
+### `{` as argument (blocks)
 
 Option `parse_brace`.  Braces after commands start block arguments.  To change
 to a directory named `{`, quote it like `cd '{'`.
 
-### `=foo` as argument (parse_equals)
+### `=` as argument (bare assignments)
 
 Option `parse_equals`.  A statement like `x = 42` is a "bare assignment" or
 attribute.  To pass `=` to a command `x`, quote it like `x '='`.

From 6d1ce9ae8848c07f41f555f993ac3563523e9f30 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 15:49:46 +0200
Subject: [PATCH 04/30] coherently refer to use "syntax"

---
 doc/upgrade-breakage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 85b0cea8a1..99aa7f737e 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -138,7 +138,7 @@ instead.
 
 (Option `simple_word_eval` is part of group `oil:upgrade`.)
 
-## Some Strings Now Parsed, if not quoted (rarely a problem)
+## Parsed as Oil Syntax, if not quoted (rarely a problem)
 
 ### New first-word keywords (e.g. `proc`, `const`, `var`, `setvar`)
 

From cb5d825385b412bcf25295f2c8aa42d486d6668a Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 18:13:07 +0200
Subject: [PATCH 05/30] third-level, coherent hints

---
 doc/upgrade-breakage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 99aa7f737e..8dc5a9bbf5 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -117,7 +117,7 @@ Instead, write `'rfoo'` if that's what you mean.
 
 ## Unsupported Syntax
 
-### No Extended Globs in Word Evaluation
+### No Extended Globs in Word Evaluation, but eggex
 
 Like regular globs, the extended glob syntax is used in two ways:
 

From 6bcd1f238f485e0ca0eb32cc7065131b6dbc6787 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 18:16:51 +0200
Subject: [PATCH 06/30] hint coherence / like =foo

---
 doc/upgrade-breakage.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 8dc5a9bbf5..2d09184ea0 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -145,10 +145,10 @@ instead.
 Oil has new keywords like `proc`, `const`, `var`, and `setvar`.  To use them
 as command names, quote them like `'proc'`.
 
-### `=foo` as first-word, is too similar to `= foo`
+### `=foo` as first-word (too similar to `= foo`)
 
-To avoid confusion with Oil's `=` operator, a word like `=foo` can't be the first word in a command.
-To invoke such commands, quote them like `'=x'`.
+To avoid confusion with Oil's `=` operator, words starting with `=` can't be the first word in a command.
+To invoke such commands, quote them like `'=foo'`.
 
 There is very little reason to use commands like `'proc'` an, `'=x'`, so you
 will likely never run into this!

From 96159cbc9c35ca43ac9ca57e1b0b646fd221ebae Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 18:23:08 +0200
Subject: [PATCH 07/30] shorten keyword hint

---
 doc/upgrade-breakage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 2d09184ea0..488f3f9d00 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -140,7 +140,7 @@ instead.
 
 ## Parsed as Oil Syntax, if not quoted (rarely a problem)
 
-### New first-word keywords (e.g. `proc`, `const`, `var`, `setvar`)
+### New first-word keywords (`proc`, `var` etc.)
 
 Oil has new keywords like `proc`, `const`, `var`, and `setvar`.  To use them
 as command names, quote them like `'proc'`.

From bf74175f883071f22231c24d51fbeb484ffeb0f8 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 18:34:40 +0200
Subject: [PATCH 08/30] s/prob/usually ok

---
 doc/upgrade-breakage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 488f3f9d00..f7b326e96e 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -138,7 +138,7 @@ instead.
 
 (Option `simple_word_eval` is part of group `oil:upgrade`.)
 
-## Parsed as Oil Syntax, if not quoted (rarely a problem)
+## Oil Syntax Parsed, if not quoted (usually ok)
 
 ### New first-word keywords (`proc`, `var` etc.)
 

From c31f7a0707538cbaa6b42d5532782e27e1a5c36b Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 19:06:17 +0200
Subject: [PATCH 09/30] shorten header

---
 doc/upgrade-breakage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index f7b326e96e..52f5cdc175 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -138,7 +138,7 @@ instead.
 
 (Option `simple_word_eval` is part of group `oil:upgrade`.)
 
-## Oil Syntax Parsed, if not quoted (usually ok)
+## Syntax Parsed, if not quoted (usually ok)
 
 ### New first-word keywords (`proc`, `var` etc.)
 

From 5ff186fc4e06bbd06792cead0a6752e68731c1cd Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 19:25:00 +0200
Subject: [PATCH 10/30] correct @foo

---
 doc/upgrade-breakage.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 52f5cdc175..0c841b11c3 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -145,7 +145,7 @@ instead.
 Oil has new keywords like `proc`, `const`, `var`, and `setvar`.  To use them
 as command names, quote them like `'proc'`.
 
-### `=foo` as first-word (too similar to `= foo`)
+### `=foo` as command (too similar to `= foo`)
 
 To avoid confusion with Oil's `=` operator, words starting with `=` can't be the first word in a command.
 To invoke such commands, quote them like `'=foo'`.
@@ -153,12 +153,12 @@ To invoke such commands, quote them like `'=foo'`.
 There is very little reason to use commands like `'proc'` an, `'=x'`, so you
 will likely never run into this!
 
-### `@foo` as argument (splices)
+### `@foo` as command or argument (now splice)
 
 Option `parse_at`.  In Oil, `@` is used to splice arrays.  To pass a string
 `@foo` to a command, quote it like `'@foo'`.
 
-### `{` as argument (blocks)
+### `{` as argument (now block)
 
 Option `parse_brace`.  Braces after commands start block arguments.  To change
 to a directory named `{`, quote it like `cd '{'`.

From 684055acc8cc8fcc40ceaf8e4e86913ffd7b440b Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 19:30:57 +0200
Subject: [PATCH 11/30] mention `=` keyword (referred to by next, explaing
 item)

---
 doc/upgrade-breakage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 0c841b11c3..00d4c935be 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -142,7 +142,7 @@ instead.
 
 ### New first-word keywords (`proc`, `var` etc.)
 
-Oil has new keywords like `proc`, `const`, `var`, and `setvar`.  To use them
+Oil has new keywords like `proc`, `const`, `var`, `setvar`, and `=`.  To use them
 as command names, quote them like `'proc'`.
 
 ### `=foo` as command (too similar to `= foo`)

From 6bf5f1a022e4240e118293fc6fcc3d42a3103c55 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 19:47:03 +0200
Subject: [PATCH 12/30] restore listing most significant first

---
 doc/upgrade-breakage.md | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 00d4c935be..927de95f2a 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -140,19 +140,6 @@ instead.
 
 ## Syntax Parsed, if not quoted (usually ok)
 
-### New first-word keywords (`proc`, `var` etc.)
-
-Oil has new keywords like `proc`, `const`, `var`, `setvar`, and `=`.  To use them
-as command names, quote them like `'proc'`.
-
-### `=foo` as command (too similar to `= foo`)
-
-To avoid confusion with Oil's `=` operator, words starting with `=` can't be the first word in a command.
-To invoke such commands, quote them like `'=foo'`.
-
-There is very little reason to use commands like `'proc'` an, `'=x'`, so you
-will likely never run into this!
-
 ### `@foo` as command or argument (now splice)
 
 Option `parse_at`.  In Oil, `@` is used to splice arrays.  To pass a string
@@ -168,6 +155,18 @@ to a directory named `{`, quote it like `cd '{'`.
 Option `parse_equals`.  A statement like `x = 42` is a "bare assignment" or
 attribute.  To pass `=` to a command `x`, quote it like `x '='`.
 
+### New first-word keywords (`proc`, `var` etc.)
+
+Oil has new keywords like `proc`, `const`, `var`, `setvar`, and `=`.  To use them
+as command names, quote them like `'proc'`.
+
+### `=foo` as command (too similar to `= foo`)
+
+To avoid confusion with Oil's `=` operator, words starting with `=` can't be the first word in a command.
+To invoke such commands, quote them like `'=foo'`.
+
+There is very little reason to use commands like `'proc'` an, `'=x'`, so you
+will likely never run into this!
 
 
 ## Summary

From 87566ea6229c9768ff5b2a7d3c4a544c181db377 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 19:55:09 +0200
Subject: [PATCH 13/30] move bare assignment (in blocks) down

---
 doc/upgrade-breakage.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 927de95f2a..0d24ace26f 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -150,11 +150,6 @@ Option `parse_at`.  In Oil, `@` is used to splice arrays.  To pass a string
 Option `parse_brace`.  Braces after commands start block arguments.  To change
 to a directory named `{`, quote it like `cd '{'`.
 
-### `=` as argument (bare assignments)
-
-Option `parse_equals`.  A statement like `x = 42` is a "bare assignment" or
-attribute.  To pass `=` to a command `x`, quote it like `x '='`.
-
 ### New first-word keywords (`proc`, `var` etc.)
 
 Oil has new keywords like `proc`, `const`, `var`, `setvar`, and `=`.  To use them
@@ -168,6 +163,11 @@ To invoke such commands, quote them like `'=foo'`.
 There is very little reason to use commands like `'proc'` an, `'=x'`, so you
 will likely never run into this!
 
+### `=` as argument within blocks (bare assignments)
+
+Option `parse_equals`.  A statement like `x = 42` within a block is a "bare assignment" of a constant or
+attribute.  To pass `=` to a command `foo`, quote it as in `foo '='`.
+
 
 ## Summary
 

From 7699258f908c0c2f7e238a7bbd8d0ad97163b141 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 20:01:51 +0200
Subject: [PATCH 14/30] oops, correction

---
 doc/upgrade-breakage.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 0d24ace26f..f3d5e04f3f 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -150,6 +150,11 @@ Option `parse_at`.  In Oil, `@` is used to splice arrays.  To pass a string
 Option `parse_brace`.  Braces after commands start block arguments.  To change
 to a directory named `{`, quote it like `cd '{'`.
 
+### `=` as argument within blocks (bare assignments)
+
+Option `parse_equals`.  A statement like `x = 42` within a block is a "bare assignment" of a constant or
+attribute.  To pass `=` to a command `foo`, quote it as in `foo '='`.
+
 ### New first-word keywords (`proc`, `var` etc.)
 
 Oil has new keywords like `proc`, `const`, `var`, `setvar`, and `=`.  To use them
@@ -160,13 +165,10 @@ as command names, quote them like `'proc'`.
 To avoid confusion with Oil's `=` operator, words starting with `=` can't be the first word in a command.
 To invoke such commands, quote them like `'=foo'`.
 
-There is very little reason to use commands like `'proc'` an, `'=x'`, so you
-will likely never run into this!
+There is very little reason for external commands like `'proc'` or `'=foo'`, so you
+will likely never run into these!
 
-### `=` as argument within blocks (bare assignments)
 
-Option `parse_equals`.  A statement like `x = 42` within a block is a "bare assignment" of a constant or
-attribute.  To pass `=` to a command `foo`, quote it as in `foo '='`.
 
 
 ## Summary

From 151132fa9b9b312f2b2cc648ce47ffd6cab3ac0d Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 20:25:19 +0200
Subject: [PATCH 15/30] only talk about "simple word evaluation" / improvements

---
 doc/upgrade-breakage.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index f3d5e04f3f..a35e39c724 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -115,9 +115,9 @@ Instead, write `'rfoo'` if that's what you mean.
 
 (Option `parse_raw_string` is part of group `oil:upgrade`.)
 
-## Unsupported Syntax
+## Unsupported Syntax, improved alternatives
 
-### No Extended Globs in Word Evaluation, but eggex
+### No Extended Globs in Simple Word Evaluation
 
 Like regular globs, the extended glob syntax is used in two ways:
 

From f82b4763c9741c743a757f106b55dd99c23a0bff Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 22:22:07 +0200
Subject: [PATCH 16/30] -> some quotes may be needed

---
 doc/upgrade-breakage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index a35e39c724..c6221ade6b 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -138,7 +138,7 @@ instead.
 
 (Option `simple_word_eval` is part of group `oil:upgrade`.)
 
-## Syntax Parsed, if not quoted (usually ok)
+## Some Quotes May Be Needed (rare occasions)
 
 ### `@foo` as command or argument (now splice)
 

From 54ddf8e962232f0c7dd66962dd2ee90cb1470276 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 22:23:16 +0200
Subject: [PATCH 17/30] s/some/few quotes

---
 doc/upgrade-breakage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index c6221ade6b..e11caefa45 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -138,7 +138,7 @@ instead.
 
 (Option `simple_word_eval` is part of group `oil:upgrade`.)
 
-## Some Quotes May Be Needed (rare occasions)
+## Few Quotes May Be Needed (rare occasions)
 
 ### `@foo` as command or argument (now splice)
 

From 6bb428c5a110658b58343aaa748d3d2190b00b30 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 22:39:52 +0200
Subject: [PATCH 18/30] list split/glob/maybe requirement (simple word eval)

---
 doc/upgrade-breakage.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index e11caefa45..0fedc3e068 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -115,7 +115,12 @@ Instead, write `'rfoo'` if that's what you mean.
 
 (Option `parse_raw_string` is part of group `oil:upgrade`.)
 
-## Unsupported Syntax, improved alternatives
+## Disabled Syntax, improved alternatives
+
+### No Implicit Split/Glob/Maybe of Variables
+
+Expanded variables are *not* automatically split, globbed, and omitted if empty (sensible default).
+Where needed use an explicit `@split()` (shortcut `@`), `@glob()`,`@maybe()` or its non-splitting `$` counterpart.
 
 ### No Extended Globs in Simple Word Evaluation
 

From 3c2213ffa58b1e7d114f535716d13eda2b13e8c6 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 22:50:52 +0200
Subject: [PATCH 19/30] mv simple word eval to "changed syntax"

---
 doc/upgrade-breakage.md | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 0fedc3e068..42d85288a0 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -75,9 +75,18 @@ Yes:
 
 (Option `parse_paren` is part of group `oil:upgrade`.)
 
+
+### Simple Word Eval, no implicit split/glob/maybe
+
+Expanded variables are *not* automatically split, globbed, and omitted if empty (sensible default).
+
+Where string-based, not array/dict-based, operation is really wanted or needed,
+use an explicit `@split()` (shortcut `@`), `@glob()`,`@maybe()` or its non-splitting `$` counterpart.
+
+
 ### `@()` is spliced command sub, not extended glob 
 
-Oil doesn't have implicit word splitting, so we want `@(seq 3)` to be
+As Oil doesn't have implicit word splitting, we want `@(seq 3)` to be
 consistent with `$(hostname)`.  They're related in the same way that `@myarray`
 and `$mystr` are.
 
@@ -115,12 +124,8 @@ Instead, write `'rfoo'` if that's what you mean.
 
 (Option `parse_raw_string` is part of group `oil:upgrade`.)
 
-## Disabled Syntax, improved alternatives
-
-### No Implicit Split/Glob/Maybe of Variables
 
-Expanded variables are *not* automatically split, globbed, and omitted if empty (sensible default).
-Where needed use an explicit `@split()` (shortcut `@`), `@glob()`,`@maybe()` or its non-splitting `$` counterpart.
+## Disabled Syntax, improved alternatives
 
 ### No Extended Globs in Simple Word Evaluation
 

From 1f7b2ca1f506360455debcb2c87aa23ea7f49698 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 23:02:04 +0200
Subject: [PATCH 20/30] remove (only duplicated) discouraged subshell idiom

---
 doc/upgrade-breakage.md | 39 ++-------------------------------------
 1 file changed, 2 insertions(+), 37 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 42d85288a0..7cabdfffd6 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -34,46 +34,11 @@ Now onto the breakages.  Most of them are **unlikely**, but worth noting.
 
 ### `if ( )` and `while ( )` take expressions, not subshell commands
 
-Code like `if ( ls /tmp )` is valid shell, but it's almost always a **misuse**
+Option `parse_paren`.  Code like `if ( ls /tmp )` is valid shell, but it's almost always a **misuse**
 of the language.  Parentheses mean **subshell**, not grouping as in C or
 Python.
 
-In Oil:
-
-- Use `if (x > 0)` for true/false expressions
-- Use the `forkwait` builtin for subshells, which are uncommon.  
-  - It's like a sequence of the `fork` builtin (replacing `&`) and the `wait`
-    builtin.
-
-No:
-
-    ( not_changed=foo )
-    echo $not_changed
-
-Yes:
-
-    forkwait {
-      setvar not_changed = 'foo'
-    }
-    echo $not_changed
-
-Note that the idiom of running commands in a different dir no longer requires
-a subshell:
-
-No:
-
-    ( cd /tmp; echo $PWD )
-    echo $PWD  # still the original value
-
-Yes:
-
-    cd /tmp {
-      echo $PWD 
-    }
-    echo $PWD  # restored
-
-
-(Option `parse_paren` is part of group `oil:upgrade`.)
+In Oil the parens in `if (x > 0)` denote a true/false expression.
 
 
 ### Simple Word Eval, no implicit split/glob/maybe

From 63e0c4511ce73a303889cf675986a50658a16d7d Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 23:05:42 +0200
Subject: [PATCH 21/30] last two, non-splitting

---
 doc/upgrade-breakage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 7cabdfffd6..752068f758 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -46,7 +46,7 @@ In Oil the parens in `if (x > 0)` denote a true/false expression.
 Expanded variables are *not* automatically split, globbed, and omitted if empty (sensible default).
 
 Where string-based, not array/dict-based, operation is really wanted or needed,
-use an explicit `@split()` (shortcut `@`), `@glob()`,`@maybe()` or its non-splitting `$` counterpart.
+use an explicit `@split()` (shortcut `@`), `@glob()`,`@maybe()` or the non-splitting `$` counterparts of the last two.
 
 
 ### `@()` is spliced command sub, not extended glob 

From 32b3ca9bad4976b2723bac9090db1c07f3972679 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 23:25:03 +0200
Subject: [PATCH 22/30] fixed awkward language

---
 doc/upgrade-breakage.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 752068f758..c8af7848e9 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -35,7 +35,7 @@ Now onto the breakages.  Most of them are **unlikely**, but worth noting.
 ### `if ( )` and `while ( )` take expressions, not subshell commands
 
 Option `parse_paren`.  Code like `if ( ls /tmp )` is valid shell, but it's almost always a **misuse**
-of the language.  Parentheses mean **subshell**, not grouping as in C or
+of the language.  Because parentheses mean **subshell**, not grouping as in C or
 Python.
 
 In Oil the parens in `if (x > 0)` denote a true/false expression.
@@ -51,11 +51,11 @@ use an explicit `@split()` (shortcut `@`), `@glob()`,`@maybe()` or the non-split
 
 ### `@()` is spliced command sub, not extended glob 
 
-As Oil doesn't have implicit word splitting, we want `@(seq 3)` to be
-consistent with `$(hostname)`.  They're related in the same way that `@myarray`
+As Oil doesn't have implicit word splitting, we want `@(seq 3)` to be the splitting
+variant of the command sub `$(seq 3)`.  They're related in the same way as `@myarray`
 and `$mystr` are.
 
-This means that `@()` is no longer extended glob, and `,()` is an alias.
+This means that `@()` is no longer an extended glob, however `,()` is its substitute.
 
 No:
 
@@ -101,7 +101,7 @@ Like regular globs, the extended glob syntax is used in two ways:
    - Bash boolean expressions like `[[ x == !(*.cc|*.h) ]]`
 2. Word Evaluation
    - commands like `cp !(*.cc|*.h) /tmp`
-   - arrays like `local -a myarray=( !(*.cc|*.h) )`
+   - array definitions like `local -a myarray=( !(*.cc|*.h) )`
    - Shell-style `for` loops
 
 Extended globs are **not** supported in [Simple Word

From 72eaf61f541057e24618036da98b66f406807b29 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 23:37:36 +0200
Subject: [PATCH 23/30] positive simple-word-eval wording

---
 doc/upgrade-breakage.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index c8af7848e9..541a484a68 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -43,9 +43,10 @@ In Oil the parens in `if (x > 0)` denote a true/false expression.
 
 ### Simple Word Eval, no implicit split/glob/maybe
 
-Expanded variables are *not* automatically split, globbed, and omitted if empty (sensible default).
+Variables are expanded reliably *without* implicitly and often surprisingly getting
+split, globbed, and omitted if empty (sensible default).
 
-Where string-based, not array/dict-based, operation is really wanted or needed,
+Where string-magic-based, i.e. not array/dict-based, operation is really wanted or needed,
 use an explicit `@split()` (shortcut `@`), `@glob()`,`@maybe()` or the non-splitting `$` counterparts of the last two.
 
 

From 3271d1edb7ec71c0fabe041f38e05f1f9104b0d1 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 23:43:06 +0200
Subject: [PATCH 24/30] cohrent mention of option group members

---
 doc/upgrade-breakage.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 541a484a68..0a34ec3a5e 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -5,7 +5,7 @@ default_highlighter: oil-sh
 What Breaks When You Upgrade to Oil
 ===================================
 
-Only a few things break when you put this at the top of a shell script:
+Only a few things break when you enable this option group at the top of a shell script:
 
     shopt --set oil:upgrade
 
@@ -52,7 +52,7 @@ use an explicit `@split()` (shortcut `@`), `@glob()`,`@maybe()` or the non-split
 
 ### `@()` is spliced command sub, not extended glob 
 
-As Oil doesn't have implicit word splitting, we want `@(seq 3)` to be the splitting
+Option `parse_at`.  As Oil doesn't have implicit word splitting, we want `@(seq 3)` to be the splitting
 variant of the command sub `$(seq 3)`.  They're related in the same way as `@myarray`
 and `$mystr` are.
 
@@ -66,11 +66,10 @@ Use this Oil alias instead:
 
     echo ,(*.cc|*.h)
 
-(Option `parse_at` is part of group `oil:upgrade`.)
 
 ### `r'c:\Users\'` is a raw string, not joined strings
 
-The meaning of `\` within string literals can be confusing, so Oil
+Option `parse_raw_string`.  The meaning of `\` within string literals can be confusing, so Oil
 distinguishes them like this:
 
 - `$'foo\n'` 
@@ -88,7 +87,6 @@ The prefix **changes** the meaning of commands like:
 
 Instead, write `'rfoo'` if that's what you mean.
 
-(Option `parse_raw_string` is part of group `oil:upgrade`.)
 
 
 ## Disabled Syntax, improved alternatives

From 388cf219d9de11b05bdcbb367ef52525ee5dea62 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 23:50:08 +0200
Subject: [PATCH 25/30] impr. explanation

---
 doc/upgrade-breakage.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 0a34ec3a5e..2d45f9b19d 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -52,9 +52,9 @@ use an explicit `@split()` (shortcut `@`), `@glob()`,`@maybe()` or the non-split
 
 ### `@()` is spliced command sub, not extended glob 
 
-Option `parse_at`.  As Oil doesn't have implicit word splitting, we want `@(seq 3)` to be the splitting
-variant of the command sub `$(seq 3)`.  They're related in the same way as `@myarray`
-and `$mystr` are.
+Option `parse_at`.  As Oil doesn't have implicit word splitting, we wanted `@(seq 3)` to be the splitting
+variant of the command sub `$(seq 3)`.  So, they're now related in the same way as `@myarray`
+and `$mystr`.
 
 This means that `@()` is no longer an extended glob, however `,()` is its substitute.
 

From 535d20a238b42dee07ea6dd25acc7ab113a9e7dd Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Tue, 14 Jun 2022 23:55:18 +0200
Subject: [PATCH 26/30] mention simple_word_eval (option group)

---
 doc/upgrade-breakage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 2d45f9b19d..9fe76d8987 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -43,7 +43,7 @@ In Oil the parens in `if (x > 0)` denote a true/false expression.
 
 ### Simple Word Eval, no implicit split/glob/maybe
 
-Variables are expanded reliably *without* implicitly and often surprisingly getting
+Option `simple_word_eval`.  Variables are expanded reliably *without* implicitly and often surprisingly getting
 split, globbed, and omitted if empty (sensible default).
 
 Where string-magic-based, i.e. not array/dict-based, operation is really wanted or needed,

From 680291f41d491f4eb73262910d40050ce119d094 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Wed, 15 Jun 2022 00:00:40 +0200
Subject: [PATCH 27/30] simple_word_eval, coherent mention

---
 doc/upgrade-breakage.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 9fe76d8987..720826a2a9 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -93,7 +93,7 @@ Instead, write `'rfoo'` if that's what you mean.
 
 ### No Extended Globs in Simple Word Evaluation
 
-Like regular globs, the extended glob syntax is used in two ways:
+Option `simple_word_eval`.  Like regular globs, the extended glob syntax is used in two ways:
 
 1. Pattern matching 
    - `case` 
@@ -110,7 +110,6 @@ after upgrading.
 You may want to use the `find` command or [Egg expressions](eggex.html)
 instead.
 
-(Option `simple_word_eval` is part of group `oil:upgrade`.)
 
 ## Few Quotes May Be Needed (rare occasions)
 

From 5d77ee7acd2ec480aa19aa387a904f6bab757a24 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Wed, 15 Jun 2022 00:12:45 +0200
Subject: [PATCH 28/30] impr. desc simple_word_eval

---
 doc/upgrade-breakage.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 720826a2a9..acfb145f16 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -41,13 +41,13 @@ Python.
 In Oil the parens in `if (x > 0)` denote a true/false expression.
 
 
-### Simple Word Eval, no implicit split/glob/maybe
+### Simple Word Eval, may need explicit split/glob/maybe
 
 Option `simple_word_eval`.  Variables are expanded reliably *without* implicitly and often surprisingly getting
 split, globbed, and omitted if empty (sensible default).
 
 Where string-magic-based, i.e. not array/dict-based, operation is really wanted or needed,
-use an explicit `@split()` (shortcut `@`), `@glob()`,`@maybe()` or the non-splitting `$` counterparts of the last two.
+add an explicit `@split()` (shortcut `@..`), `@glob()`,`@maybe()` or the non-splitting `$`-counterparts of the last two.
 
 
 ### `@()` is spliced command sub, not extended glob 

From 148885241557f978a654fc7264a8112ca302c027 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Wed, 15 Jun 2022 00:33:21 +0200
Subject: [PATCH 29/30] osh defaults

---
 doc/upgrade-breakage.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index acfb145f16..292389833c 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -25,8 +25,8 @@ First, let's emphasize the **good** things that happen when you upgrade:
 - [Reliable Error Handling](error-handling.html) becomes the default.
 - ... and more
 
-You can also use `bin/osh` indefinitely, in which case you **don't** need to
-read this doc.  [OSH]($xref:osh-language) is a highly compatible Unix shell.
+In case you only want to use `bin/osh` defaults you **don't** need to read this doc.
+[OSH]($xref:osh-language) is a highly compatible Unix shell.
 
 ## Syntax Changes
 

From a15f006b49f036b3a7624d589e373daf20e0d725 Mon Sep 17 00:00:00 2001
From: bar-g <105970722+bar-g@users.noreply.github.com>
Date: Wed, 15 Jun 2022 00:35:35 +0200
Subject: [PATCH 30/30] mv bin/osh case up

---
 doc/upgrade-breakage.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/upgrade-breakage.md b/doc/upgrade-breakage.md
index 292389833c..3a8d0c2e86 100644
--- a/doc/upgrade-breakage.md
+++ b/doc/upgrade-breakage.md
@@ -11,6 +11,9 @@ Only a few things break when you enable this option group at the top of a shell
 
 This doc enumerates and explains them.
 
+In case you only want to use the `bin/osh` defaults, you **don't** need to read this doc.
+[OSH]($xref:osh-language) is a highly compatible Unix shell.
+
 <div id="toc">
 </div>
 
@@ -25,8 +28,6 @@ First, let's emphasize the **good** things that happen when you upgrade:
 - [Reliable Error Handling](error-handling.html) becomes the default.
 - ... and more
 
-In case you only want to use `bin/osh` defaults you **don't** need to read this doc.
-[OSH]($xref:osh-language) is a highly compatible Unix shell.
 
 ## Syntax Changes