doc: More ReadMe improvements

Author: ingydotnet

ReadMe.md

@@ -6,11 +6,11 @@ Program in YAML — Code is Data
 
 ## About YS / YAMLScript
 
-[YS](https://yamlscript.org) is a new YAML loader for 15 (and counting)
-programming languages:
+**[YS](https://yamlscript.org) (aka YAMLScript) is a new YAML loader** for 15
+(and counting) programming languages:  
 [C#](https://www.nuget.org/packages/YAMLScript/),
 [Clojure](https://clojars.org/org.yamlscript/clj-yamlscript),
-[Crystal](https://github.com/yaml/yamlscript/crystal)
+[Crystal](https://shardbox.org/shards/yamlscript),
 [Go](https://github.com/yaml/yamlscript-go),
 [Haskell](https://hackage.haskell.org/package/yamlscript),
 [Java](https://clojars.org/org.yamlscript/yamlscript),
@@ -24,67 +24,68 @@ programming languages:
 [Ruby](https://rubygems.org/gems/yamlscript) and
 [Rust](https://crates.io/crates/yamlscript).
 
-You should consider trying out YS to replace your current YAML loader, because:
+Try using YS in place of your current YAML loader!
 
-* It's easy to use
+* It's as easy to use as your current YAML loader
+  * Loads your existing YAML files properly
 * It works the same way in every programming language
-  * Same features, same bugs, same bug fixes
+  * Same API, same features, same bugs, same bug fixes
 * YS has optional functional programming features
   * File imports, string interpolation, standard library, etc
   * Everything a compiled programming language has
 
 How can YS offer all this?
 
-YS is also a functional programming language!
+**YS is also a functional programming language!**
 
 Like [PyYAML](https://pyyaml.org/) and many other YAML loaders, YS is
 implemented to the [YAML 1.2 specification](https://yaml.org/spec/1.2.2/).
-But instead of loading YAML into its intended data structure, a YS loader loads
-YAML into a Lisp AST (abstract syntax tree) data structure.
-The AST is then rendered into Lisp code and evaluated, resulting in
-the intended data structure.
+But instead of loading YAML into directly into its intended data structure, a YS
+loader loads YAML into a Lisp AST (abstract syntax tree) data structure.
+The AST is then rendered into Lisp code and evaluated by a full-featured
+runtime, resulting in the intended data structure.
 
 The specific Lisp is [Clojure](https://clojure.org/), which is very capable,
 mature and well-documented programming language with a large ecosystem of
 libraries and tools.
 
-You may be aware that Clojure is a JVM hosted language (and also a JavaScript
-hosted one via ClojureScript), but YS doesn't need either of those.
-YS is compiled to a native binary executable and also a native shared library.
-The shared library can be used by nearly any programming language, including the
-ones listed above.
+> Note: You may be aware that Clojure is a JVM hosted language (and also a
+> JavaScript hosted one via ClojureScript), but YS doesn't need either of those.
+> YS is compiled to a native binary executable and also a native shared library.
+> The shared library can be used by nearly any programming language, including
+> the ones listed above.
 
-Not only can you use YS as a loader libraryfrom a programming language, but you
+Not only can you use YS as a loader library from a programming language, but you
 can also use it from the command line with the `ys` command.
 
 YS is awesome for:
 
 * Querying, manipulating and transforming YAML (and JSON) files
   * Outputs include YAML, JSON, CSV, TSV and EDN
-* Refactoring large monolythic YAML files into smaller, more manageable files
-* Using data in your YAML files from external sources
+* Refactoring large monolithic YAML files into smaller, more manageable files
+* Using data from external sources in your YAML files
   * Files, web, databases, APIs, shell commands, etc
 * Applying over 1000 built-in functions to your YAML data
 * Using YS libraries for even more functionality
 * Writing complete programs, applications, automation scripts
 
-> Note: YS is an official language on the
-> [Exercism](https://exercism.org/tracks) (free) language learning site!
-> It's a great way to learn how to program in YS.
+**YS is an official language on the
+[Exercism](https://exercism.org/tracks) (free) language learning site!**  
+It's a great way to learn how to program in YS.
 
 
-### Using YS
-
-First you need to install `ys` and `libys`.
-You can install both to `~/.local/bin/ys` and `~/.local/lib/libys.so`
-respectively, with:
+## A Quick Example
 
+First you'll need to install `ys` and/or `libys`.
+You can install them both to `~/.local/bin/ys` and `~/.local/lib/libys.so`
+respectively, with this single command:
 ```bash
 curl https://yamlscript.org/install | bash
 ```
-See the [Installing YS](#installing-ys) section below for more details.
 
-Now say you have a file called `file.ys` that looks like this:
+> See [Installing YS](https://yamlscript.org/doc/install/) for full details.
+
+Now say you have a file called `file.yaml` that looks like this:
 ```yaml
 name: Fido
 age: 6
@@ -94,24 +95,23 @@ likes: [running, fetching, playing, treats]
 
 You can load it with:
 ```bash
-ys --json file.ys
+ys --json file.yaml
 ```
 
 And get this output:
 ```json
-{
-  "name": "Fido",
-  "age": 6,
-  "dog years": 42,
-  "likes": ["running", "fetching", "playing", "treats"]
-}
+{"name":"Fido",
+ "age":6,
+ "dog years":42,
+ "likes":["fetching", "playing", "running", "treats"]}
 ```
 
-Wait, that's just regular YAML! Exactly! YS is 100% compatible with existing
-YAML files.
-But here's where it gets interesting...
+Nothing special here.
+YS is 100% compatible with existing YAML files, so this is just what you'd
+expect.
 
-Let's say you want to calculate the dog years dynamically:
+But here's where it gets interesting...
+Let's say you want to add some dynamic logic:
 
 ```yaml
 !YS-v0:
@@ -120,29 +120,29 @@ age =: 6
 name: Fido
 age:: age
 dog years:: age * 7
-likes: [running, fetching, playing, treats]
+likes::
+  sort:: [running, fetching, playing, treats]
 ```
 
-Now when you load it, the dog years are calculated automatically!
+The first line is a special tag that tells YS that this file may contain code.
 The `age =: 6` sets a variable, and the `::` tells YS that the value is a code
 expression, not a data value.
+We've also used the standard `sort` function to sort the `likes` list.
 
+Let's load it via a Python using the `yamlscript.py` module this time:
+```bash
+python3 -c '
+import json, yamlscript;
+print(json.dumps(yamlscript.YAMLScript()
+                 .load(open("file.yaml").read())))' 
+{"name": "Fido", "age": 6, "dog years": 42,
+ "likes": ["fetching", "playing", "running", "treats"]}
+```
 
-### Why YS is Different
-
-With YS, YAML files can either be "loaded" or "run".
-When a YS program is loaded, it evaluates to a JSON-model data structure.
-When a YS program is run, it is executed as a normal program.
-
-If you have a valid YAML ([1.2 Core Schema](
-https://yaml.org/spec/1.2.2/#103-core-schema)) file that doesn't use custom
-tags, and loads to a value expressible in JSON, then it will load properly with
-YS.
-The YS `load` operation will evaluate that file exactly the same in any
-programming language / environment.
+The good stuff is all sorted and the dog years are calculated automatically!
 
 
-### Real-World Examples
+## Real-World Examples
 
 Want to merge multiple YAML files with environment variable overrides?
 
@@ -212,12 +212,12 @@ deployments::
 -->
 
 
-### Getting Started with YS
+## Getting Started with YS
 
 There are two primary ways to use YS:
 
 * Using the `ys` command line runner / loader / compiler / installer
-* Using a YS library in your own programming language
+* Using a YAMLScript library in your own programming language
 
 The `ys` command line tool is the easiest way to get started with YS.
 You can use it to load / evaluate / transform YAML files and print the result as
@@ -228,8 +228,8 @@ You can also use YS as a library in your own programming language.
 For example, in Python you can use the `yamlscript` module like this:
 
 ```python
-import yamlscript
-ys = yamlscript.YAMLScript()
+from yamlscript import YAMLScript
+ys = YAMLScript()
 text = open("foo.yaml").read()
 data = ys.load(text)
 ```
@@ -241,7 +241,7 @@ YS is supported on these operating systems:
 
 * Linux
 * macOS
-* Windows  (work in progress)
+* Windows  (coming soon)
 
 YS is supported on these architectures:
 
@@ -250,9 +250,14 @@ YS is supported on these architectures:
 
 For now other systems cannot be supported because `ys` and `libys` are compiled
 by GraalVM's `native-image` tool, which only supports the above systems.
+However, work is underway to have YS use alternate runtimes such as JVM, Go,
+JavaScript and WebAssembly.
+
 
+## Usage Examples in Your Language
 
-### Quick Examples in Your Language
+Here's some examples of how to use YS in a few different programming languages.
+Usage in other languages is similar.
 
 **Python:**
 ```python
@@ -263,16 +268,15 @@ config = ys.load(open('config.yaml').read())
 
 **JavaScript/Node:**
 ```javascript
-const YS = require('@yaml/yamlscript');
-const ys = new YS();
-const config = ys.load(fs.readFileSync('config.yaml', 'utf8'));
+YS = require('@yaml/yamlscript');
+ys = new YS();
+config = ys.load(fs.readFileSync('config.yaml', 'utf8'));
 ```
 
 **Go:**
 ```go
 import "github.com/yaml/yamlscript-go"
-ys := yamlscript.New()
-data, _ := ys.Load(yamlContent)
+data, err := ys.Load(yamlContent)
 ```
 
 **Ruby:**
@@ -283,98 +287,20 @@ config = ys.load(File.read('config.yaml'))
 ```
 
 
-### Why Choose YS?
-
-* **🔧 Reliability** - Same implementation across all languages means consistent behavior
-* **📦 Zero Dependencies** - Single shared library with no runtime dependencies
-* **🎯 100% YAML Compatible** - Works with all your existing YAML files today
-* **🚀 Performance** - Native compiled code runs as fast or faster than Python/Perl
-* **💪 Powerful When Needed** - Access to 1000+ built-in functions and full Clojure ecosystem
-* **🌐 Universal** - One syntax to learn, use everywhere
-
-
-## Installing YS
-
-You can install the YS `ys` interpreter and/or its `libys.so` shared
-library from pre-built binaries or building from source.
-Both are very easy to do.
-
-
-### Installing YS Pre-built Binary Releases
-
-YS ships pre-built binaries for each release version [here](
-https://github.com/yaml/yamlscript/releases).
-
-To install a latest release for your machine platform, try:
-
-```bash
-curl https://yamlscript.org/install | bash
-```
-
-Make sure `~/.local/bin` is in your `PATH` environment variable.
-
-You can use the following environment variables to control the installation:
+## Why Choose YS?
 
-* `PREFIX=...` - The directory to install to. Default: `~/.local`
-* `VERSION=...` - The YS version to install. Default: `0.2.3`
-* `BIN=1` - Only install the `PREFIX/bin/ys` command line tool.
-* `LIB=1` - Only install the `PREFIX/lib/libys` shared library.
-* `DEBUG=1` - Print the Bash commands that are being run.
-
-Once you have installed the `ys` command you can upgrade to a bin binary
-version with `ys --upgrade`.
-
-
-### Installing YS from Source
-
-This is very easy to build and install YS from its source code because the YS
-build process has very few dependencies:
-
-* `bash` (your interactive shell can be any shell)
-* `curl`
-* `git`
-* `make`
-
-To install the `ys` command line tool, and `libys` shared library, run these
-commands:
-
-```bash
-git clone https://github.com/yaml/yamlscript
-cd yamlscript
-make build
-make install
-```
-
-That's it!
-
-See [Installing YS](https://yamlscript.org/doc/install/) for full details.
-
-
-### Installing a YS Binding for a Programming Language
-
-YS ships its language binding libraries and the `libys.so` shared library
-separately.
-
-Currently, each binding release version requires an exact version of the shared
-library, or it will not work.
-
-The best way to install a binding library is to use your programming language's
-package manager to install the latest binding version, and the YS installer to
-install the latest shared library version.
-
-So for Python you would:
-
-```bash
-pip install yamlscript
-curl https://yamlscript.org/install | bash
-```
-
-The Perl installation process can automatically install the shared library, so
-you can just do:
-
-```bash
-cpanm YAMLScript
-```
+* **🔧 Reliability** -
+  Same implementation across all languages means consistent behavior
+* **📦 Zero Dependencies** -
+  Single shared library with no runtime dependencies
+* **🎯 100% YAML Compatible** -
+  Works with all your existing YAML files today
+* **🚀 Performance** -
+  Native compiled code runs as fast or faster than Python/Perl
+* **💪 Powerful When Needed** -
+  Access to 1000+ built-in functions and full Clojure ecosystem
+* **🌐 Universal** -
+  One syntax to learn, use everywhere
 
 
 ## The YS Repository
@@ -394,7 +320,7 @@ is a mono-repo containing:
 
 The YS repository uses a `Makefile` system to build, test and install its
 various offerings.
-It installs (locally within this directory)all the dependencies you need to
+It installs (locally within this directory) all the dependencies you need to
 build and test YS, including every programming language needed by the bindings.
 
 There is a top level `Makefile` and each repo subdirectory has its own
@@ -408,8 +334,8 @@ it and run `make` targets (try `make test`) without any problems.
 
 ### Contributing to YS
 
-To ensure that YS libraries work the same across all languages, this project
-aims to have a binding implementation for each programming language.
+This project aims to have a binding implementation for each every programming
+language where YAML is used.
 
 If you would like to contribute a new YS binding for a programming language,
 you are encouraged to