Add complete documentation for the --caching option.

Add a new section in the CLI reference documentation to explain how the
cache works and how it can be controlled using the `--caching` option.

Replace the previous, shorter documentation in the SQLite tutorial by a
simple mention of the cache with a link to the newly added reference
section.

docs/cli.rst

@@ -91,6 +91,55 @@ and tracing upwards through is_a and part_of relationships:
 
  uberon viz -p i,p hand foot
 
+Cache Control
+-------------
+
+OAK may download data from remote sources as part of its normal operations. For
+example, using the :code:`sqlite:obo:...` input selector will cause OAK to
+fetch the requested Semantic-SQL database from a centralised repository.
+Whenever that happens, the downloaded data will be cached in a local directory
+so that subsequent commands using the same input selector do not have to
+download the file again.
+
+By default, OAK will refresh (download again) a previously downloaded file if
+it was last downloaded more than 7 days ago.
+
+The global option :code:`--caching` gives the user some control on how the
+cache works.
+
+To change the default cache expiry lifetime of 7 days, the :code:`--caching`
+option accepts a value of the form :code:`ND`, where *N* is a positive integer
+and *D* can be either :code:`s`, :code:`d`, :code:`w`, :code:`m`, or :code:`y`
+to indicate that *N* is a number of seconds, days, weeks, months, or years,
+respectively. If the *D* part is omitted, it defaults to :code:`d`.
+
+For example, :code:`--caching=3w` instructs OAK to refresh a cached file if it
+was last refreshed 21 days ago.
+
+The :code:`--caching` option also accepts the following special values:
+
+- :code:`refresh` to force OAK to always refresh a file regardless of its age;
+- :code:`no-refresh` to do the opposite, that is, preventing OAK from
+ refreshing a file regardless of its age;
+- :code:`clear` to forcefully clear the cache (which will trigger a refresh as
+ a consequence);
+- :code:`reset` is a synonym of :code:`clear`.
+
+Note the difference between :code:`refresh` and :code:`clear`. The former will
+only cause the requested file to be refreshed, leaving any other file that may
+exist in the cache untouched. The latter will delete all cached files, so that
+not only the requested file will be downloaded again, but any other
+previously cached file will also have to be downloaded again the next time they
+are requested.
+
+In both case, refreshing and clearing will only happen if the OAK command in
+which the :code:`--caching` option is used attempts to look up a cached file.
+Otherwise the option will have no effect.
+
+To forcefully clear the cache independently of any command, the
+:ref:`cache-clear` command may be used. The contents of the cache may be
+explored at any time with the :ref:`cache-ls` command.
+
 Commands
 -----------
 

docs/intro/tutorial07.rst

@@ -65,23 +65,8 @@ This will download the pato.db sqlite file once, and cache it.
 PyStow is used to cache the file, and the default location is ``~/.data/oaklib``.
 
 By default, a cached SQLite file will be automatically refreshed (downloaded
-again) if it is older than 7 days. That behavior can be controlled with the
-global ``--caching`` option. For example, to force OAK to always download the
-file regardless of its age:
-
-.. code-block::
-
- runoak --caching=refresh -i sqlite:obo:pato search t~shape
-
-Other possible values for the ``--caching`` option include:
-
-- ``no-refresh`` to prevent OAK from re-downloading the file even it is older
- than 7 days;
-- ``Xd`` to refresh a cached file older than _X_ days;
-- ``Xw`` to refresh a cached file older than _X_ weeks.
-
-You may also use the ``cache-clear`` command to force clearing any cached
-SQLite file at anytime.
+again) if it is older than 7 days. For details on how to alter the behavior of
+the cache, see the :ref:`Cache Control` section in the CLI documentation.
 
 Building your own SQLite files
 -------------------