Please find attached three separate documentation patches.
From 269faa44ec18bb63c61ecba4cb232ceb0e46cd10 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankan...@gmail.com>
Date: Sun, 2 Oct 2022 21:54:20 +0200
Subject: [PATCH 1/3] Add crossreference to org-stuck-projects docstring
* lisp/org-agenda.el (org-stuck-projects): Add Info manual reference
to docstring.
---
lisp/org-agenda.el | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index b608bdd29..612407c0a 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -614,13 +614,17 @@ you can then use it to define a custom command."
'("+LEVEL=2/-DONE" ("TODO" "NEXT" "NEXTACTION") nil "")
"How to identify stuck projects.
This is a list of four items:
+
1. A tags/todo/property matcher string that is used to identify a project.
- See the manual for a description of tag and property searches.
- The entire tree below a headline matched by this is considered one project.
+ See Info node `(org) Matching tags and properties' for a
+ description of tag and property searches. The entire tree
+ below a headline matched by this is considered one project.
+
2. A list of TODO keywords identifying non-stuck projects.
If the project subtree contains any headline with one of these todo
keywords, the project is considered to be not stuck. If you specify
\"*\" as a keyword, any TODO keyword will mark the project unstuck.
+
3. A list of tags identifying non-stuck projects.
If the project subtree contains any headline with one of these tags,
the project is considered to be not stuck. If you specify \"*\" as
@@ -628,6 +632,7 @@ This is a list of four items:
the explicit presence of a tag somewhere in the subtree, inherited
tags do not count here. If inherited tags make a project not stuck,
use \"-TAG\" in the tags part of the matcher under (1.) above.
+
4. An arbitrary regular expression matching non-stuck projects.
If the project turns out to be not stuck, search continues also in the
--
2.30.2
From f0af8f8e68e3953455c7ef5d08651da39ef86a01 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankan...@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 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
From 2ac3989b3b1b03549df72ef955f0c49b2f62ebec Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankan...@gmail.com>
Date: Sun, 2 Oct 2022 21:54:31 +0200
Subject: [PATCH 3/3] Improve documentation of org-kill-line
* lisp/org.el (org-special-ctrl-k): Doc fix; clarify what is being
killed and improve wording. Add command substitutions.
(org-kill-line): Doc fix; mention user options that this command
relies on.
---
lisp/org.el | 20 +++++++++++++-------
1 file changed, 13 insertions(+), 7 deletions(-)
diff --git a/lisp/org.el b/lisp/org.el
index 036384a04..004b21764 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -1527,13 +1527,15 @@ This may also be a cons cell where the behavior for `C-a' and
(const :tag "reversed: after tags first" reversed)))))
(defcustom org-special-ctrl-k nil
- "Non-nil means `C-k' will behave specially in headlines.
-When nil, `C-k' will call the default `kill-line' command.
-When t, the following will happen while the cursor is in the headline:
+ "Non-nil means that \\<org-mode-map>\\[org-kill-line] \
+will behave specially in headlines.
-- When at the beginning of a headline, kill the entire subtree.
-- When in the middle of the headline text, kill the text up to the tags.
-- When after the headline text and before the tags, kill all the tags."
+When nil, \\[org-kill-line] will call the default `kill-line' command.
+Otherwise, the following will happen when point is in a headline:
+
+- At the beginning of a headline, kill the entire line.
+- In the middle of the headline text, kill the text up to the tags.
+- After the headline text and before the tags, kill all the tags."
:group 'org-edit-structure
:type 'boolean)
@@ -19954,7 +19956,11 @@ depending on context."
(call-interactively #'forward-sentence)))))))
(defun org-kill-line (&optional _arg)
- "Kill line, to tags or end of line."
+ "Kill line, to tags or end of line.
+
+The behavior of this command depends on the user options
+`org-special-ctrl-k' and `org-ctrl-k-protect-subtree' (which
+see)."
(interactive)
(cond
((or (not org-special-ctrl-k)
--
2.30.2
