[doc] Update json doc with changes from 0.9.5

Also update the syntax table

build/doc.sh

@@ -332,8 +332,9 @@ help-cards() {
 
 tour() {
   ### Build the Oil Language Tour and execute code
+  local name=${1:-oil-language-tour}
 
-  split-and-render doc/oil-language-tour.md
+  split-and-render doc/$name.md
 
   local work_dir=$REPO_ROOT/_tmp/code-blocks
 
@@ -346,12 +347,12 @@ log() { echo "$@" 1>&2; }
 EOF
 
   pushd $work_dir
-  $REPO_ROOT/bin/oil oil-language-tour.txt
+  $REPO_ROOT/bin/oil $name.txt
   popd
 
   # My own dev tools
   if test -d ~/vm-shared; then
-    local path=_release/VERSION/doc/oil-language-tour.html 
+    local path=_release/VERSION/doc/$name.html
     cp -v $path ~/vm-shared/$path
   fi
 }

doc/json.md

@@ -1,15 +1,13 @@
+---
+default_highlighter: oil-sh
+---
+
 JSON in Oil
 ===========
 
 [JSON](https://www.json.org/) is used by both web services and command line
 tools, so a modern Unix shell needs support for it.
 
-This page describes Oil's JSON support as of December 2019 ([version
-0.7.pre8](/release/0.7.pre8)).  It will likely expand over time, depending on
-[user feedback](https://github.com/oilshell/oil/wiki/Where-To-Send-Feedback).
-
-(Note: the `help` builtin will provide shorter, reference-style documentation.)
-
 <!-- cmark.py expands this -->
 <div id="toc">
 </div>
@@ -63,58 +61,54 @@ Notes:
 
 Usage:
 
-    json write FLAGS* VAR_NAME+
+    json write FLAGS* (EXPR)
 
+    EXPR is an expression that evaluates to a serializable object.
+
     Flags:
       --indent=2     Indentation size
       --pretty=true  Whether to add newlines for readability
 
 Examples:
 
-```
-# Create a Dict.  As in JavaScript, keys don't require quotes.
-$ var d = {name: "bob", age: 42}
+    # Create a Dict.  As in JavaScript, keys don't require quotes.
+    $ var d = {name: "bob", age: 42}
 
-# Print the Dict as JSON.  By default, newlines are added for readability, with
-# 2 space indentation.
-$ json write :d
-{
-  "name": "bob",
-  "count": 42
-}
+    # Print the Dict as JSON.  By default, newlines are added for readability,
+    # with 2 space indentation.
+    $ json write (d)
+    {
+      "name": "bob",
+      "count": 42
+    }
 
-$ json write --indent 4 :d
-{
-    "name": "bob",
-    "count": 42
-}
+    $ json write --indent 4 (d)
+    {
+        "name": "bob",
+        "count": 42
+    }
 
-$ json write --pretty=F :d
-{"name": "bob", "count": 42}
-```
+    $ json write --pretty=F (d)
+    {"name": "bob", "count": 42}
 
 Notes:
 
-- `-indent` is ignored if `-pretty` is false.
-- The `json` builtin is part of the Oil language, so it uses Oil's **flag
-  syntax**, which is based on Go's.  In particular, boolean flags are written
-  `-pretty=F` rather than `-pretty F`, but you can write `-indent=4` or
-  `-indent 4`.
+- `--indent` is ignored if `--pretty` is false.
 
 ## Other Data Structures Can Be Printed as JSON
 
 Oil arrays and shell arrays both serialize to a list of strings:
 
     $ declare sharray=( foo.txt *.py )
-    $ json write :sharray
+    $ json write (sharray)
     [  
        "foo.txt",
        "one.py",
        "two.py"
     ]
 
     $ var oilarray = %( foo.txt *.py )
-    $ json write :oilarray
+    $ json write (oilarray)
     [  
        "foo.txt",
        "one.py",
@@ -124,7 +118,7 @@ Oil arrays and shell arrays both serialize to a list of strings:
 Bash-style associative arrays are printed like `Dict[Str, Str]`:
 
     $ declare -A assoc=(["key"]=value)
-    $ json write :assoc
+    $ json write (assoc)
     {
       "key": "value"
     }

doc/syntax-feelings.md

@@ -338,23 +338,25 @@ Help](oil-help-topics.html) is a better reference for users.
     @(seq 3)     Split Command Sub  Command        cmd,expr
 
     ^(echo hi)   Block Literal      Command        expr
-    { echo hi }  Block Literal      Command        cmd
+    { echo hi }  Block Literal      Command        cmd          shell requires ;
 
     >(sort -n)   Process Sub        Command        cmd          rare
     <(echo hi)   Process Sub        Command        cmd          rare
 
     %(array lit) Array Literal      Words          expr
 
-    ${.echo hi}  Builtin Sub        Words          cmd,expr     Not implemented
-    @{.echo hi}  Builtin Sub        Words          cmd,expr     Not implemented
+    ${.echo hi}  Builtin Sub        Words          cmd,expr     not implemented
+    @{.echo hi}  Builtin Sub        Words          cmd,expr     not implemented
 
     $[42 + a[i]] Stringify Expr     Expression     cmd
-    ^[42 + a[i]] Lazy Expression    Expression     expr         Not implemented
+    ^[42 + a[i]] Lazy Expression    Expression     expr         not implemented
+
+    ${x %2d}     Var Sub            Formatting     cmd,expr     not implemented
 
     json (x)     Typed Arg List     Argument       cmd
                                     Expressions
 
-    $/d+/        Inline Eggex       Eggex Expr     cmd          Not implemented
+    $/d+/        Inline Eggex       Eggex Expr     cmd          not implemented
 
     r'' r""      Raw String         String         expr         cmd when shopt
                  Literal                                        parse_raw_string
@@ -364,7 +366,9 @@ Help](oil-help-topics.html) is a better reference for users.
 
     #'a'         Char Literal       UTF-8 char     expr
 
-    ${x %.3f}    Shell Var Sub      Shell          cmd,expr     mostly deprecated
+Discouraged / Deprecated
+
+    ${x%%pre}    Shell Var Sub      Shell          cmd,expr     mostly deprecated
     $((1+2))     Shell Arith Sub    Shell Arith    cmd          deprecated
 
     @(*.py|*.sh) Extended Glob      Glob Words     cmd          deprecated