Document all the CLI commands in the manual

docs/glossary.md

@@ -1,4 +1,4 @@
-# Terminology
+# Glossary
 
 Many concepts are universal across formats and languages, but are known by
 various names nonetheless. RCL adopts the following terminology.

docs/rcl_evaluate.md

@@ -0,0 +1,20 @@
+# rcl evaluate
+
+## Synopsis
+
+    rcl evaluate <input>
+
+Shorthands:
+
+    rcl eval
+    rcl e
+
+## Description
+
+Read an RCL expression from the file `<input>`, and evaluate it. When `<input>`
+is `-`, read from stdin instead. Print the evaluated result as json to stdout.
+
+## Options
+
+TODO: This should take an `--output` option to switch between pretty json and
+compact json. And possibly we should output yaml, HCL, ...

docs/rcl_format.md

@@ -0,0 +1,21 @@
+# rcl format
+
+## Synopsis
+
+    rcl format <input>
+
+Shorthands:
+
+    rcl fmt
+    rcl f
+
+## Description
+
+Read an RCL expression from the file `<input>`, and format it according to the
+standard style. When `<input>` is `-`, read from stdin instead. Print the result
+to stdout.
+
+## Options
+
+ * TODO: There should be an `--in-place` option to write the result.
+ * TODO: There should be a `--check` option to indicate if formatting is correct.

docs/rcl_highlight.md

@@ -0,0 +1,16 @@
+# rcl highlight
+
+## Synopsis
+
+    rcl highlight <input>
+
+## Description
+
+Read an RCL expression from the file `<input>`, and print a syntax-highlighted
+result to stout. When `<input>` is `-`, read from stdin instead.
+
+## Options
+
+TODO: There should be an option to write html instead of ansi escape codes, or
+some other format that could easily be consumed, for example to integrate with
+Pygments. Or maybe only some directives to compare against an external lexer.

docs/rcl_query.md

@@ -0,0 +1,25 @@
+# rcl query
+
+## Synopsis
+
+    rcl query <input> <expr>
+
+Shorthands:
+
+    rcl q
+
+## Description
+
+Evaluate an expression against an input.
+
+ * Read an RCL expression from the file `<input>`. When `<input>` is `-`,
+   read from stdin instead.
+ * Evaluate the expression `<expr>`, in a context where the variable `input`
+   is bound to the result of the input document.
+
+This can be used to peek into a sub-element of a document that evaluates to a
+large expression, but it can also be used for ad-hoc data querying, as an
+alternative to jq. For example:
+
+    echo '[12, 42, 33]' | rcl q - '[for x in input: f"Double {x} is {x * 2}."]'
+    ["Double 12 is 24.","Double 42 is 84.","Double 33 is 66."]

mkdocs.yml

@@ -16,9 +16,14 @@ markdown_extensions:
 nav:
   - "Overview": "index.md"
   - "User guide":
-    - "Syntax highlighting": "syntax_highlighting.md"
-    - "Terminology": "terminology.md"
-    - "Syntax": "syntax.md"
-    - "Strings": "strings.md"
-    - "Null": "null.md"
+      - "Syntax highlighting": "syntax_highlighting.md"
+      - "Syntax": "syntax.md"
+      - "Strings": "strings.md"
+      - "Null": "null.md"
+      - "Glossary": "glossary.md"
+  - "Reference":
+      - "rcl evaluate": "rcl_evaluate.md"
+      - "rcl format": "rcl_format.md"
+      - "rcl highlight": "rcl_highlight.md"
+      - "rcl query": "rcl_query.md"
   - "Development": "development.md"