Docs: Add examples and update readme

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:
+  ;; Show an agenda-like view of all habits in all agenda files:
-  (org-agenda-ng org-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:

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
+