[elpa] externals/org e28e3aaabb 3/4: Improve documentation of org-agenda-skip-*

[ELPA Syncer]

branch: externals/org
commit e28e3aaabba696444cf4f8243034602bc5824dc1
Author: Stefan Kangas <stefankangas@gmail.com>
Commit: Ihor Radchenko <yantar92@gmail.com>

    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 e4c4606877..b1642343a3 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 bbb22029c7..6069c0ec61 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -4200,12 +4200,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)
@@ -5118,12 +5125,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)
@@ -5145,8 +5158,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.