fixup! rewrite the docs

docs/commands.txt

@@ -64,5 +64,3 @@ Every command starts with a ``\`` character.
 |                        |                                                     |
 |                        | Works as a toggle.                                  |
 +------------------------+-----------------------------------------------------+
-
-

docs/compatibility.txt

@@ -4,11 +4,12 @@
 Compatibility
 =============
 
-.. NOTE::
+.. CAUTION::
 
-   We recommend that you use the version of Crash that is bundled with the
-   version of CrateDB that you are using. This minimises the chances of
-   compatibility issues.
+   We recommend that you upgrade to the latest stable version of CrateDB
+   whenever possible. And we also recommend that you use the version of Crash
+   that is bundled with the version of CrateDB that you are using. This
+   greatly minimises the chances of experiencing compatibility issues.
 
 CrateDB tries to maintain `backwards`_ and `forwards`_ compatibility. However,
 this is not always possible.
@@ -25,13 +26,13 @@ Known compatibility issues:
   CrateDB versions 0.39 and later allow you to insert nested arrays using
   `array constructors`_, and nested objects using `object literals`_.
 
-.. note::
-
-    Crash client commands are available since version ``0.11.x``!
+- Crash client :ref:`commands <commands>` are only available since version 0.11
+  and later.
 
 .. _array constructors: https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#array-constructor
 .. _backwards: https://en.wikipedia.org/wiki/Backward_compatibility
 .. _client library: https://crate.io/docs/crate/getting-started/en/latest/start-building/index.html
+.. _CrateDB REST endpoint: https://crate.io/docs/crate/reference/en/latest/interfaces/http.html
 .. _forwards: https://en.wikipedia.org/wiki/Forward_compatibility
 .. _information schema: https://crate.io/docs/crate/reference/en/latest/general/information-schema.html
 .. _object literals: https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#object-literals

docs/formats.txt

@@ -4,8 +4,10 @@
 Response Formats
 ================
 
-Crash supports multiple output formats that you can select between using either
-:ref:`commands` or :ref:`options`.
+Crash supports multiple output formats.
+
+You can select between these output formats using either :ref:`commands` or
+:ref:`options`.
 
 .. rubric:: Table of Contents
 
@@ -38,8 +40,8 @@ For example:
 ``json``
 ========
 
-Query results are printed as a JSON formatted object array. Keys hold the column
-name, and the key value holds the row value.
+Query results are printed as a `JSON`_ formatted object array. Keys hold the
+column name, and the key value holds the row value.
 
 .. TIP::
 
@@ -65,62 +67,59 @@ Here's an example::
 ``json_row``
 ============
 
-Query results are printed as a JSON formatted object array, like
-:ref:`format-json`. However, each row gets its own line.
-
-.. TIP::
-
-   This format is compatible with `COPY FROM`_ for re-importing data.
-
-Here's an example::
+Query results are printed as a JSON formatted object array, like the
+:ref:`format-json` format. However, each row gets its own line. For example::
 
   {"name": "crate1", "version": "0.46.3"}
   {"name": "crate2", "version": "0.46.3"}
 
 
+.. TIP::
+
+   This format is compatible with `COPY FROM`_ for re-importing data.
+
 .. _format-csv:
 
 ``csv``
 =======
 
-Query results are printed using a `comma separated value`_ (CSV) format.
+Query results are printed as `comma separated values`_ (CSV).
 
 Specifically:
 
 - The delimiter is a comma (``,``)
 - The quote character is an apostrophe (``'``)
 - The escape character is a reverse solidus (``\``)
 
-.. NOTE::
-
-   Column headers that contain a single quote (e.g. nested objects) will be
-   escaped.
-
-The first line of the csv output contains the name of the selected columns.
-
-Example::
+The first line of the CSV output contains the name of the selected columns::
 
     name,version
     crate1,0.46.3
     crate2,0.46.3
 
-However, ``objects`` or ``arrays`` are returned as a (``JSON``-) string:
 
-Example::
+``object`` types and ``array`` types are returned as a JSON string::
 
     name,settings[\'udc\']
-    crate,'{"enabled": true, "initial_delay": "10m", "interval": "1d", "url": "https://udc.crate.io"}'
-
+    crate,'{"enabled": true, "initial_delay": "10m"}'
 
 .. _format-raw:
 
 ``raw``
 =======
 
-The ``raw`` format prints the results as it is retured by the CrateDB Python library.
-It contains a JSON object with 4 keys: ``cols``, ``rows``, ``rowcount``, and ``duration``.
+Query results are printed as the raw JSON produced by `the CrateDB Python
+client library`_ used by Crash.
 
-Example::
+This JSON structure provides:
+
+- A ``rows`` key for holding a list of rows
+- A ``cols`` key for holding a list of column titles
+- A ``rowcount`` key which holds the total number of rows returned
+- A ``duration`` key which holds the total duration of the query execution in
+  seconds
+
+Here's an example::
 
     {
       "rows": [
@@ -138,16 +137,19 @@ Example::
         "0.46.3"
       ],
       "rowcount": 1,
-      "duration": 0.000
+      "duration": 0.00477246
     }
 
 .. _format-mixed:
 
 ``mixed``
 =========
 
-The ``mixed`` output lists each column in a row and multiple rows are separated by a line delimiter.
-The name of the column is on the left, separated by ``|`` from the value on the right side.
+Query results are printed as a plain text formatted table.
+
+However, unlike the :ref:`format-tabluar` format, each row (separated by ``-``
+characters) contains the column title and column value (separated by the ``|``
+character).
 
 Example::
 
@@ -158,5 +160,7 @@ Example::
     version | 0.46.3
     ---------------------------------------------------------------
 
+.. _comma separated values: https://en.wikipedia.org/wiki/Comma-separated_values
 .. _COPY FROM: https://crate.io/docs/crate/reference/en/latest/general/dml.html#import-and-export
-.. _comma separated value: https://en.wikipedia.org/wiki/Comma-separated_values
+.. _JSON: https://www.json.org/
+.. _the CrateDB Python client library: https://crate.io/docs/clients/python/en/latest/

docs/getting-started.txt

@@ -83,9 +83,9 @@ You should see something like this:
 .. _Command Line Arguments: https://crate.io/docs/projects/crash/en/stable/cli.html
 .. _crate-python: https://pypi.python.org/pypi/crate/
 .. _CrateDB REST Endpoint: https://crate.io/docs/current/sql/rest.html
+.. _CrateDB: https://crate.io/products/cratedb/
 .. _PATH: https://en.wikipedia.org/wiki/PATH_(variable)
 .. _PyPI overview: https://pypi.python.org/pypi/crash/
-.. _STDOUT: https://en.wikipedia.org/wiki/Standard_streams
-.. _CrateDB: https://crate.io/products/cratedb/
 .. _Running CrateDB: https://crate.io/docs/crate/reference/en/latest/run.html
 .. _shell: https://en.wikipedia.org/wiki/Shell_(computing)
+.. _STDOUT: https://en.wikipedia.org/wiki/Standard_streams

docs/index.txt

@@ -7,6 +7,20 @@ The CrateDB Shell
 The CrashDB Shell (aka *Crash*) is an interactive `command-line interface`_
 (CLI) tool for interacting with CrateDB.
 
+.. sidebar:: Screnshots
+
+   .. image:: startup.png
+       :alt: A screenshot of Crash after startup
+       :target: getting-started.html#query
+
+   .. image:: autocomplete.png
+       :alt: A screenshot of Crash after executing a query
+       :target: getting-started.html#query
+
+   .. image:: query.png
+       :alt: A screenshot of Crash after executing a query
+       :target: getting-started.html#query
+
 .. rubric:: Table of Contents
 
 .. toctree::
@@ -18,5 +32,5 @@ The CrashDB Shell (aka *Crash*) is an interactive `command-line interface`_
    formats
    compatibility
 
-.. _PATH: https://en.wikipedia.org/wiki/PATH_(variable)
 .. _command-line interface: https://en.wikipedia.org/wiki/Command-line_interface
+.. _PATH: https://en.wikipedia.org/wiki/PATH_(variable)

docs/run.txt

@@ -231,8 +231,8 @@ In both instances:
 
 .. _command-line: https://en.wikipedia.org/wiki/Command-line_interface
 .. _jq: http://stedolan.github.io/jq/
-.. _piping: https://www.wikiwand.com/en/Pipeline_(Unix)
 .. _pipe: https://www.wikiwand.com/en/Pipeline_(Unix)
+.. _piping: https://www.wikiwand.com/en/Pipeline_(Unix)
 .. _redirecting: https://www.tldp.org/LDP/abs/html/io-redirection.html
 .. _STDOUT: https://en.wikipedia.org/wiki/Standard_streams
 .. _user configuration directory: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html