doc/getting-started: basic sort, add usage table

doc/getting-started.md

@@ -5,12 +5,14 @@ default_highlighter: oil-sh
 Getting Started
 ===============
 
-There are many ways to use Oil!
+Oilshell provides a **multi-purpose interpreter** runtime.
 
-- You can use it *interactively*, or you can write "shell scripts" with it.
-  Shell is the best language for *ad hoc* automation.
-- You can use it in *compatible* mode with `bin/osh`, or in *legacy-free* mode
-  with `bin/oil`.
+- You can use it *interactively*, or run and write "shell scripts" for it.</br>
+  (Shell is the best language for *ad hoc* automation.)
+
+- You can start it to use a language that's *compatible* with other shells (using `bin/osh`),</br>
+  or, to use the much improved Oil language, a very coherent *pitfall-freed* shell upgrade with</br>
+  selected python/js/etc. features (using `bin/oil`).
 
 As of 2021, the [OSH language][osh-language] is mature, and the [Oil
 language][oil-language] is under development.  The interactive shell exists,
@@ -22,24 +24,23 @@ See [blog posts tagged #FAQ][blog-faqs] for more detail.
 [oil-language]: https://www.oilshell.org/cross-ref.html?tag=oil-language#oil-language
 [osh-language]: https://www.oilshell.org/cross-ref.html?tag=osh-language#osh-language
 
-This doc walks you through setting up Oil, explains some concepts, and links to
-more documentation.
 
 <!-- cmark.py expands this -->
 <div id="toc">
 </div>
 
-## Setup
+## Install / Setup / Config (move this into INSTALL ?)
 
-### Downloading Oil
+### Download
 
-The [releases page](https://www.oilshell.org/releases.html) links to source
-tarballs for every release.  It also links to the documentation tree, which
-includes this page.
+The [releases page](https://www.oilshell.org/releases.html) links to downloads
+and documentation (incl. this page) for every release.
 
-### Your Configuration Dir
+After downloading follow the instructions in [INSTALL](INSTALL.html)
 
-After running the instructions in [INSTALL](INSTALL.html), run:
+### Optional Configuration Directory
+
+After creating the directory:
 
     mkdir -p ~/.config/oil
 
@@ -67,18 +68,79 @@ them in your `oshrc`.
 I describe my own `oshrc` file on the Wiki: [How To Test
 OSH](https://github.com/oilshell/oil/wiki/How-To-Test-OSH).
 
-## Tips
 
 - If you get tired of typing `~/.config/oil/oshrc`, symlink it to `~/.oshrc`.
 
-### Troubleshooting
 
-- If you're running OSH from `bash` or `zsh`, then the prompt string `$PS1` may
-  be unintentionally inherited.  Running `PS1=''` before `bin/osh` avoids this.
-  This is also true for `$PS2`, `$PS4`, etc.
-- On Arch Linux and other distros,`$LANG` may not get set without
-  `/etc/profile`.  Adding `source /etc/profile` to your `oshrc` may solve this
-  problem.
+
+
+## Oilshell Usage (as osh and oil)
+
+
+<table>
+<thead>  <tr>
+     <th>
+       Task
+     </th>
+     <th>
+       Usage
+     </th>
+ </tr></thead>
+ <tbody> <tr>
+     <td>
+       **Running an existing script** as initially written for other shells. </br>* Usually not even minimal quoting/spacing adjustments needed. <br/><br/>([Particular adjustments](https://www.oilshell.org/release/latest/doc/known-differences.html) may only be required due to implementing the "Common Subset" of consistent and sane shell execution compatibility. For example, if a script was using an inconsistent associative array pattern, or relied on dynamic parsing.) </br></br>NB: By default, basic Oil language features without a side-effect beyond occupying namespace do already work as well (e.g. `const`/`var`/`setvar` incl. Oil expressions, `read --line/all/qsn/-0/...`, `write`, etc). So, these only break in other shells if not shipping a fallback.
+     </td>
+     <td>
+       Execute script in osh interpreter:</br>`osh my.sh`</br><br/></br> Or, adapt script, and let it begin with: </br>```#!/usr/bin/env osh```
+     </td>
+  </tr>
+    <tr>
+     <td>
+       **...and, lint shell fragilities.** <br/> * Improved scripts will run with less errors in other shells.</br><br/>NB: The example on the right enables all strict options at once, but individual strict_* options allow fixing issue by issue.
+     </td>
+     <td>
+       Add a line near the top of the script, to set a shell option with error fallback (keep #!/shebang):</br>`shopt --set strict:all  2>/dev/null || true`</br><br/> *After that* execute the script in osh:</br>`osh my.sh`
+     </td>
+  </tr>
+    <tr>
+     <td>
+       **...and, allow adding new Oil language syntax.**  <br/> * Adjustments to legacy code will only be needed for a [minimized amount of limited syntax](https://www.oilshell.org/release/latest/doc/deprecations.html). <br/> * However, adding new syntax/semantics to a script will drop compatibility with other shells.</br><br/>(The adjustments needed in legacy code should mostly be just quoting/spacing, for disambiguation. Except, requirements for proper error handling, and for explicit split/glob functions on variables due to the default [Simple Word Evaluation](http://www.oilshell.org/release/latest/doc/simple-word-eval.html). Of course only where variables were originally left correctly(!) unquoted and split/globbed.)
+     </td>
+     <td>
+       Adapt script to begin with: </br>`#!/usr/bin/env osh` </br> `shopt --set oil:upgrade`
+     </td>
+  </tr>
+    <tr>
+     <td>
+       Coming pretty close to the Oil interpreter. <br/>(Intersection of osh & oil & strict.)
+     </td>
+     <td>
+       `#!/usr/bin/env osh` </br>  `shopt --set oil:upgrade strict:all`</br><!-- prevent line breaks: --> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+     </td>
+  </tr>
+    <tr>
+     <td>
+       **Using all of the Oil interpeter.** </br>* Implements all positive features of classic shells, compatibly. </br>* All identified pitfalls removed. </br>* Gracefully adding the best from Python, JavaScript and others.<br/><br/> (Everything parsed as Oil syntax. Only unavoidable Oil language warts remain.) 
+     </td>
+     <td>
+       Adapt script to begin with:</br> `#!/usr/bin/env osh` </br> `shopt --set oil:all`</br></br> Or, simply use:</br> `#!/usr/bin/env oil`
+     </td>
+  </tr>
+</tbody>
+</table>
+
+
+ For more information see: https://www.oilshell.org/release/latest#Documentation
+
+
+### What Is Expected to Run Under OSH
+
+"Batch" programs are most likely to run unmodified under OSH.  On the other
+hand, Interactive programs like `.bashrc` and bash completion scripts may
+require small changes.
+
+- Wiki: [What Is Expected to Run Under OSH]($wiki)
+
 
 ### `sh` and Bash Docs Are Useful for OSH
 
@@ -87,16 +149,24 @@ generally don't teach the quirks that OSH disallows.  For example, much of the
 information and advice in [BashGuide][] can be used without worrying about
 which shell you're using.  See the end of this manual for more resources.
 
-For this reason, we're focusing efforts on documenting the [Oil
+For this reason, we're focusing the documenting efforts on the [Oil
 language][oil-language].
 
-## What Is Expected to Run Under OSH
 
-"Batch" programs are most likely to run unmodified under OSH.  On the other
-hand, Interactive programs like `.bashrc` and bash completion scripts may
-require small changes.
 
-- Wiki: [What Is Expected to Run Under OSH]($wiki)
+
+## Troubleshooting
+
+- If you're running OSH from `bash` or `zsh`, then the prompt string `$PS1` may
+  be unintentionally inherited.  Running `PS1=''` before `bin/osh` avoids this.
+  This is also true for `$PS2`, `$PS4`, etc.
+- On Arch Linux and other distros,`$LANG` may not get set without
+  `/etc/profile`.  Adding `source /etc/profile` to your `oshrc` may solve this
+  problem.
+
+
+
+
 
 ## Features Unique to OSH
 
@@ -201,13 +271,20 @@ Related:
 
 This is implemented, but a JSON library isn't in the release build.
 
-### More
+
+
+
+
+## Features Unique to Oil
 
 For more features unique to Oil, see [Why Use Oil?][why]
 
 [why]: https://www.oilshell.org/why.html
 
 
+
+
+
 ## Appendix
 
 ### Bugs