From 8618f12fce7cb3c35019fd6da8bb4c7c094418a9 Mon Sep 17 00:00:00 2001
From: Jakub Roztocil <jakub@roztocil.co>
Date: Tue, 24 Aug 2021 17:18:45 +0200
Subject: [PATCH] Tweak format options docs

---
 README.rst | 20 ++++++++------------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/README.rst b/README.rst
index e7286088..be572c98 100644
--- a/README.rst
+++ b/README.rst
@@ -1560,16 +1560,17 @@ One of these options can be used to control output processing:
                        Default for redirected output.
 ====================   ========================================================
 
-You can control the applied formatting via the `formatting options`_.
+You can further control the applied formatting via the more granular `format options`_.
 
 
-Formatting options
-------------------
+Format options
+--------------
 
+The ``--format-options`` option allows you to control how the output should be formatted when formatting is applied.
 The following options are available:
 
 +-------------------------------+---------------+------------------------------+
-| Option                        | Default value | Shortcut(s)                  |
+| Option                        | Default value | Shortcuts                    |
 +===============================+===============+==============================+
 | ``headers.sort``              | ``true``      | ``--sorted``, ``--unsorted`` |
 +-------------------------------+---------------+------------------------------+
@@ -1587,14 +1588,9 @@ sorting, and specify a custom JSON indent size:
 
     $ http --format-options headers.sort:false,json.sort_keys:false,json.indent:2 pie.dev/get
 
-There are also shortcuts that allow you to quickly disable and re-enable options.
-For example, ``--sorted`` and ``--unsorted`` arguments would respectively enable
-and disable sorting-related format options:
-
-.. code-block:: bash
-
-    $ http --sorted pie.dev/get
-    $ http --unsorted pie.dev/get
+There are also two shortcuts that allow you to quickly disable and re-enable
+sorting-related format options (currently it means JSON keys and headers):
+``--unsorted`` and ``--sorted``.
 
 This is something you will typically store as one of the default options in your `config`_ file.