From f0af8f8e68e3953455c7ef5d08651da39ef86a01 Mon Sep 17 00:00:00 2001 From: Stefan Kangas 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 d249f32d6..5de4f93c7 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -21159,6 +21159,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:161]. Then to selectively pick diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el index 612407c0a..9189bbafb 100644 --- a/lisp/org-agenda.el +++ b/lisp/org-agenda.el @@ -4203,12 +4203,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) @@ -5121,12 +5128,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) @@ -5148,8 +5161,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