From d0c890d14382d3b4d1c0259f76f2478a0d1700ae Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sun, 2 Oct 2022 21:54:27 +0200
Subject: [PATCH 2/3] Improve documentation of org-agenda-skip-*

* doc/org-manual.org (Special Agenda Views): Improve indexing.
* lisp/org-agenda.el (org-agenda-skip-function)
(org-agenda-skip-entry-if, org-agenda-skip-subtree-if): Expand
docstrings.
(org-agenda-skip-if): Doc fix; clarify wording.
---
 doc/org-manual.org |  2 ++
 lisp/org-agenda.el | 33 +++++++++++++++++++++++----------
 2 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index a20c8e50b..ddba84cab 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -21345,6 +21345,8 @@ meaningful string suitable for the agenda view.
 
 #+vindex: org-odd-levels-only
 #+vindex: org-agenda-skip-function
+#+findex: org-agenda-skip-entry-if
+#+findex: org-agenda-skip-subtree-if
 Search for entries with a limit set on levels for the custom search.
 This is a general approach to creating custom searches in Org.  To
 include all levels, use =LEVEL>0=[fn:: Note that, for
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index 5b8133e81..cadf5ffb8 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -4204,12 +4204,19 @@ to t."
 If this function returns nil, the current match should not be skipped.
 Otherwise, the function must return a position from where the search
 should be continued.
-This may also be a Lisp form, it will be evaluated.
-Never set this variable using `setq' or so, because then it will apply
-to all future agenda commands.  If you do want a global skipping condition,
-use the option `org-agenda-skip-function-global' instead.
-The correct usage for `org-agenda-skip-function' is to bind it with
-`let' to scope it dynamically into the agenda-constructing command.
+
+This may also be a Lisp form that will be evaluated.  Useful
+forms include `org-agenda-skip-entry-if' and
+`org-agenda-skip-subtree-if'.  See the Info node `(org) Special
+Agenda Views' for more details and examples.
+
+Never set this variable using `setq' or similar, because then it
+will apply to all future agenda commands.  If you want a global
+skipping condition, use the option `org-agenda-skip-function-global'
+instead.
+
+The correct way to use `org-agenda-skip-function' is to bind it with `let'
+to scope it dynamically into the agenda-constructing command.
 A good way to set it is through options in `org-agenda-custom-commands'.")
 
 (defun org-agenda-skip (&optional element)
@@ -5122,12 +5129,18 @@ bind it in the options section.")
 
 (defun org-agenda-skip-entry-if (&rest conditions)
   "Skip entry if any of CONDITIONS is true.
-See `org-agenda-skip-if' for details."
+See `org-agenda-skip-if' for details about CONDITIONS.
+
+This function can be put into `org-agenda-skip-function' for the
+duration of a command."
   (org-agenda-skip-if nil conditions))
 
 (defun org-agenda-skip-subtree-if (&rest conditions)
   "Skip subtree if any of CONDITIONS is true.
-See `org-agenda-skip-if' for details."
+See `org-agenda-skip-if' for details about CONDITIONS.
+
+This function can be put into `org-agenda-skip-function' for the
+duration of a command."
   (org-agenda-skip-if t conditions))
 
 (defun org-agenda-skip-if (subtree conditions)
@@ -5149,8 +5162,8 @@ notregexp     Check if regexp does not match.
 todo          Check if TODO keyword matches
 nottodo       Check if TODO keyword does not match
 
-The regexp is taken from the conditions list, it must come right after
-the `regexp' or `notregexp' element.
+The regexp is taken from the conditions list, and must come right
+after the `regexp' or `notregexp' element.
 
 `todo' and `nottodo' accept as an argument a list of todo
 keywords, which may include \"*\" to match any todo keyword.
-- 
2.30.2