From 056c93bcd61539eecf2fdd4d6bbae4af026e279d Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Tue, 10 Jul 2018 08:38:17 -0500
Subject: [PATCH] Docs: Add examples and update readme

---
 README.org   | 12 +++++++-----
 examples.org | 20 ++++++++++++++++++++
 2 files changed, 27 insertions(+), 5 deletions(-)
 create mode 100644 examples.org

diff --git a/README.org b/README.org
index 3758a90..99dde6e 100644
--- a/README.org
+++ b/README.org
@@ -17,19 +17,19 @@ Here's an example of generating a kind of agenda view for today (note that the g
 Here are some other examples:
 
 #+BEGIN_SRC elisp
-  ;; Show an agenda-like view of items in all agenda files with TODO and SOMEDAY keywords which are
+  ;; Show an agenda-like view of items in "~/org/main.org" with TODO and SOMEDAY keywords which are
   ;; tagged "computer" or "Emacs" and in the category "main":
-  (org-agenda-ng org-agenda-files
+  (org-agenda-ng "~/org/main.org"
     (and (todo "TODO" "SOMEDAY")
          (tags "computer" "Emacs")
          (category "main")))
 
-  ;; Show an agenda-like view of all habits:
-  (org-agenda-ng org-agenda-files
+  ;; Show an agenda-like view of all habits in all agenda files:
+  (org-agenda-ng
     (habit))
 
   ;; Show an agenda-like view similar to a "traditional" Org agenda:
-  (org-agenda-ng "~/org/main.org"
+  (org-agenda-ng
     (or (habit)
         (date = today)
         (deadline <=)
@@ -38,6 +38,8 @@ Here are some other examples:
              (closed = today))))
 #+END_SRC
 
+More examples are available in [[examples.org]].
+
 ** org-ql
 
 Another way to look at it is like a "query language" for Org buffers.  For example:
diff --git a/examples.org b/examples.org
new file mode 100644
index 0000000..7ac0002
--- /dev/null
+++ b/examples.org
@@ -0,0 +1,20 @@
+
+
+* Examples
+
+** Showing TO-READ entries containing the word "lisp"
+
+This query would be difficult to write in a standard Org Agenda search, because it matches against a to-do keyword /and/ a plain-text search.  As described in the [[https://orgmode.org/worg/org-tutorials/advanced-searching.html#combining-metadata-and-full-text-queries][advanced searching tutorial]], it would require using ~org-search-view~ with a query with specific regular expression syntax, like this:
+
+#+BEGIN_EXAMPLE
+  +lisp +{^\*+\s-+TO-READ\s-}
+#+END_EXAMPLE
+
+But with =org-ql= or =org-agenda-ng=, you would write:
+
+#+BEGIN_SRC elisp
+  (org-agenda-ng
+    (and (regexp "lisp")
+         (todo "TO-READ")))
+#+END_SRC
+