Docs: Explain how caching works

Fixes #132.  Thanks to Mikhail Skorzhinskii (@mskorzhinskiy) for
suggesting.

org-ql.info

@@ -607,7 +607,20 @@ File: README.info,  Node: Listing / acting-on results,  Prev: Agenda-like views,
 4.3.2 Listing / acting-on results
 ---------------------------------
 
-  1. Function: ‘org-ql-select’
+  1. Caching
+
+     Org QL uses a per-buffer cache to speed up subsequent searches.
+     It’s keyed on query expressions, which means that, for the same
+     query in the same buffer, if the buffer has not been modified since
+     the last time the query was run, the cached result will be
+     returned, and the query will not be evaluated in that buffer again.
+
+     Therefore, since query expressions are not guaranteed to be
+     evaluated when these functions are called, they should be free of
+     side effects.  Any side effects should be done in the action
+     expression instead.
+
+  2. Function: ‘org-ql-select’
 
      _Arguments:_ ‘(buffers-or-files query &key action narrow sort)’
 
@@ -667,7 +680,7 @@ File: README.info,  Node: Listing / acting-on results,  Prev: Agenda-like views,
             '(todo "WAITING"))
           ;; => ((headline (:raw-value "Visit the moon" ...) ...) ...)
 
-  2. Function: ‘org-ql-query’
+  3. Function: ‘org-ql-query’
 
      _Arguments:_ ‘(&key (select 'element-with-markers) from where
      order-by narrow)’
@@ -712,7 +725,7 @@ File: README.info,  Node: Listing / acting-on results,  Prev: Agenda-like views,
             :where '(todo "WAITING"))
           ;; => ((headline (:raw-value "Visit the moon" ...) ...) ...)
 
-  3. Macro: ‘org-ql’
+  4. Macro: ‘org-ql’
 
      _Arguments:_ ‘(buffers-or-files query &key sort narrow markers
      action)’
@@ -1336,33 +1349,33 @@ Node: Date/time predicates17145
 Node: Functions / Macros19800
 Node: Agenda-like views20055
 Node: Listing / acting-on results21460
-Node: Dynamic block26062
-Node: Links28760
-Node: Tips29447
-Node: Changelog29765
-Node: 05-pre30449
-Node: 04931688
-Node: 04831966
-Node: 04732313
-Node: 04632708
-Node: 04533108
-Node: 04433467
-Node: 04333824
-Node: 04234019
-Node: 04134178
-Node: 0434419
-Node: 03238352
-Node: 03138731
-Node: 0338928
-Node: 02341903
-Node: 02242131
-Node: 02142399
-Node: 0242598
-Node: 0146633
-Node: Notes46734
-Node: Comparison with Org Agenda searches46896
-Node: org-sidebar47768
-Node: License48047
+Node: Dynamic block26655
+Node: Links29353
+Node: Tips30040
+Node: Changelog30358
+Node: 05-pre31042
+Node: 04932281
+Node: 04832559
+Node: 04732906
+Node: 04633301
+Node: 04533701
+Node: 04434060
+Node: 04334417
+Node: 04234612
+Node: 04134771
+Node: 0435012
+Node: 03238945
+Node: 03139324
+Node: 0339521
+Node: 02342496
+Node: 02242724
+Node: 02142992
+Node: 0243191
+Node: 0147226
+Node: Notes47327
+Node: Comparison with Org Agenda searches47489
+Node: org-sidebar48361
+Node: License48640
 
 End Tag Table