Document review contexts

1 files changed, 66 insertions, 0 deletions

diff --git a/README.org b/README.org
index 5b6056d..69404e0 100644
--- a/README.org
+++ b/README.org
@@ -266,6 +266,65 @@ Tags can be added to this list using ~(add-to-list 'org-fc-card-tags
 See also:
 - [[file:doc/review_internals.org][Review Internals]]
 - [[file:doc/review_history.org][Review History]]
+** Review Contexts
+By default, two contexts are defined:
+
+- all :: all cards in ~org-fc-directories~
+- buffer :: all cards in the current buffer
+
+New contexts can be defined by adding them to the alist
+~org-fc-custom-contexts~.
+
+Contexts have the form ~(:paths paths :filter filter)~.
+
+- ~:paths~ (optional)
+  either a list of paths, a single path
+  or ~'buffer~ for the current buffer.
+  Paths don't have to be included in the ~org-fc-directories~.
+  Defaults to ~org-fc-directories~.
+- ~:filter~ (optional), a card filter defaulting to a filter that
+  matches all cards.
+
+Filters can be combinations of the following expressions:
+
+- ~(and ex1 ex2 ...)~
+- ~(or ex1 ex2 ...)~
+- ~(not ex)~
+- ~(tag "tag")~
+- ~(type card-type) or (type "card-type")~
+
+*** Examples
+All double cards with tag "math":
+#+begin_src emacs-lisp
+  (add-to-list org-fc-custom-contexts
+    '(double-math-cards . (:filter (and (type double) (tag "math")))))
+#+end_src
+
+All cards in that don't have one of the tags "foo" and "bar":
+#+begin_src emacs-lisp
+  (add-to-list org-fc-custom-contexts
+    '(no-foo-bar-cards . (:filter (not (or (tag "foo") (tag "bar"))))))
+#+end_src
+
+All cards in =~/combinatorics/= or =~/number_theory.org=:
+#+begin_src emacs-lisp
+  (add-to-list org-fc-custom-contexts
+    '(math-cards . (:paths ("~/combinatorics/" "~/number_theory.org"))))
+#+end_src
+
+All cards in =~/combinatorics/= with tag "theorem":
+#+begin_src emacs-lisp
+  (add-to-list org-fc-custom-contexts
+    '(combinatorics-theorems .
+      (:paths "~/combinatorics/" :filter (tag "theorem"))))
+#+end_src
+
+All double cards in the current buffer:
+#+begin_src emacs-lisp
+  (add-to-list org-fc-custom-contexts
+    '(current-double .
+      (:paths buffer :filter (type double))))
+#+end_src
 ** Dashboard / Statistics
 ~org-fc-dashboard~ shows a buffer with statistics for review performance
 and cards / card types.
@@ -288,7 +347,14 @@ upcoming changes.
 
 In case a update to the org sources is needed, I'll add a changelog
 entry with updating instructions.
+*** [2020-05-01 Fri]
+**** Internal
+The AWK scripts now generate S-expressions instead of CSV tables, this
+way ~read~ can be used to parse the data instead of relying on a set
+of custom parsing functions.
 
+This also allows passing more complex data structures from AWK to
+org-fc.
 *** [2020-04-29 Wed]
 Implemented a new version of the spacing algorithm (SM2) that's used
 by org-fc.