[doc] Update tour, FAQ, and warts based on feedback.

Great feedback here!

https://lobste.rs/s/9dcsmn/tour_oil_language

Still TODO: Reduce the conceptual part up front.  That makes sense for
the END of the doc.

doc/oil-language-faq.md

@@ -28,7 +28,8 @@ string.  But they are different:
   - Note that `len(x)` is an expression that evaluates to an integer, and
     `$len(x)` converts it to a string.
 
-(Note: command subs may be optimized later, as `ksh` does.)
+(Note: builtin subs like `${.myproc $x}` are meant to eliminate process
+overhead, but they're not yet implemented.)
 
 ## How can I return rich values from shell functions / Oil `proc`s?
 
@@ -38,21 +39,28 @@ There are two primary ways:
   `$(myproc)` or a pipeline like `myproc | read --line`.
 - Use an "out param" with [setref]($oil-help:setref).
 
-Oil may grow true functions with the `func` keyword at some point.  However,
-that must be done carefully, as a `proc` composes with processes, but a `func`
-doesn't.
+(Oil may grow true functions with the `func` keyword, but it will be built on
+top of `proc` and the *builtin sub* mechanism.)
 
 Send us feedback if this doesn't make sense, or if you want a longer
 explanation.
 
 ## Why doesn't a raw string work here: `${array[r'\']}` ?
 
-Oil has two array index syntax:
+This boils down to the difference between OSH and Oil, and not being able to
+mix the two.  Though they look similar, `${array[i]}` syntax (with braces) is
+fundamentally different than `$[array[i]]` syntax (with brackets).
 
-- The **legacy** shell-like syntax `${array[i]}`, which accepts shell
-  arithmetic expressions (which consist of number-like strings).
-- The [Oil expression subsitution]($oil-help:expr-sub) syntax `$[array[i]]`,
-  which accepts Oil expressions (which consist of typed data).
+- OSH supports `${array[i]}`.
+  - The index is legacy/deprecated shell arithmetic like `${array[i++]}` or
+    `${assoc["$key"]}`.
+  - The index **cannot** be a raw string like `r'\'`.
+- Oil supports both, but [expression subsitution]($oil-help:expr-sub) syntax
+  `$[array[i]]` is preferred.
+  - It accepts Oil expressions like `$[array[i + 1]` or `$[mydict[key]]`.
+  - A raw string like `r'\'` is a valid key, e.g.  `$[mydict[r'\']]`.
+
+Of course, Oil style is preferred when compatibility isn't an issue.
 
 No:
 
@@ -80,3 +88,9 @@ The issue is the same as above.  Oil expression are allowed within `$[]` but
 not `${}`.
 
 -->
+
+## Related
+
+- [Oil Language FAQ]($wiki) on the wiki has more answers.  They may be migrated
+  here at some point.
+

doc/oil-language-tour.md

@@ -108,7 +108,7 @@ It also has Ruby-like blocks:
 And utilities to read and write JSON:
 
     var d = {name: 'bob', age: 42}
-    json write :d
+    json write :d  # :d refers to the variable d
     # =>
     # {
     #   "name": "bob",
@@ -625,6 +625,13 @@ Here are some categories of builtin:
 - Meta: `command  builtin  runproc  type  eval`
 - Modules: `source  module`
 
+Syntax quirk: builtins like `read` use the colon as a "pseudo-sigil":
+
+    var x = ''
+    whoami | read :x  # mutate variable x
+
+It's just a visual indication that the string arg is a variable name.
+
 <!-- TODO: Make a more comprehensive list. -->
 
 ## Expression Language: Python-like Types
@@ -694,24 +701,33 @@ More on strings:
 - The syntax `%symbol` is used in eggex, and could be an interned string.
 -->
 
-#### List
+#### List (and Arrays)
 
 All lists can be expressed with Python-like literals:
 
     var foods = ['ale', 'bean', 'corn']
     var recursive = [1, [2, 3]]
 
-Arrays of strings can be expressed with shell-like literals:
+As a special case, list of strings are called **arrays**.  They can be be
+expressed with shell-like literals:
 
     var foods = %(ale bean corn)
 
 #### Dict
 
 Dicts have a JavaScript-like syntax with unquoted keys:
 
-    var d = {name: 'bob', age: 42}
+    var d = {name: 'bob', age: 42, 'key with spaces': 'val'}
+
+    # These are synonyms.  Fatal exception if the key doesn't exist.
+    var v1 = d['name']
+    var v2 = d->name 
+
+    # Using them in a command (with expression sub):
+    echo $[d['name']]             # => bob
+    echo $[d->name]               # => bob
 
-    echo $[d['name']]  # => bob
+    echo $[d['key with spaces']]  # => val
 
     var empty = {}
 

doc/warts.md

@@ -82,6 +82,15 @@ It would have been nicer if they were consistent, but:
 - Most users won't see these literal forms very much.  They're more useful for
   testing and frameworks rather than simple scripts/applications.
 
+## In `read :x`, The Colon is a "Pseudo-Sigil"
+
+Sigils like `$` and `@` are [statically
+parsed](https://www.oilshell.org/blog/2019/02/07.html), but the optional `:` is
+dynamically parsed by every builtin that supports it.
+
+This is a minor inconsistency, but I like having a symbol for a variable to be
+mutated.
+
 ## Related 
 
 - The doc on [compatibility quirks](quirks.html) relates to the OSH language.