From 9aa5a99dffad5f5add11e2dec04b3ec4041e8f74 Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@crate.io>
Date: Fri, 12 Jan 2024 00:52:00 +0100
Subject: [PATCH] Documentation: Add section about the new `\pager` command

---
 docs/commands.rst |  3 +++
 docs/run.rst      | 24 ++++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/docs/commands.rst b/docs/commands.rst
index a040890d..a43552d1 100644
--- a/docs/commands.rst
+++ b/docs/commands.rst
@@ -49,6 +49,9 @@ Every command starts with a ``\`` character.
 |                        | - ``nodes`` (query for failing node checks)         |
 |                        | - ``cluster`` (query for failing cluster checks)    |
 +------------------------+-----------------------------------------------------+
+| ``\pager``             | Use apps like ``jless`` or ``pspg`` to              |
+|                        | view the result sets. See also :ref:`use-pager`.    |
++------------------------+-----------------------------------------------------+
 | ``\r <FILENAME>``      | Reads statements from ``<FILENAME>`` and execute    |
 |                        | them.                                               |
 +------------------------+-----------------------------------------------------+
diff --git a/docs/run.rst b/docs/run.rst
index 9e56b9e3..2177cd66 100644
--- a/docs/run.rst
+++ b/docs/run.rst
@@ -238,10 +238,34 @@ In both instances:
 - ``<DURATION>`` is the total number of seconds the query took to execute on the
   cluster
 
+
+.. _use-pager:
+
+Using a pager program
+=====================
+
+You can use applications like the `jless`_ JSON exploration tool or the
+`pspg`_ pager program to view the result sets, by utilizing the ``\pager``
+command.
+
+.. figure:: https://github.com/crate/crash/assets/38700/e7281ca0-4736-4127-9628-16126b5ea67c
+
+Example
+-------
+Use those instructions to drill down into the results of your query by
+exploring it using ``jless``, like outlined within the screencast above::
+
+    cr> \pager jless
+    cr> \format json
+    cr> SELECT * FROM sys.nodes;
+
+
 .. _command-line: https://en.wikipedia.org/wiki/Command-line_interface
+.. _jless: https://jless.io/
 .. _jq: https://stedolan.github.io/jq/
 .. _pipe: https://www.wikiwand.com/en/Pipeline_(Unix)
 .. _piping: https://www.wikiwand.com/en/Pipeline_(Unix)
+.. _pspg: https://github.com/okbob/pspg
 .. _redirecting: https://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