[PATCH] Three documentation patches

[PATCH] Three documentation patches

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 59 bytes --]

Please find attached three separate documentation patches.

[-- Attachment #2: 0001-Add-crossreference-to-org-stuck-projects-docstring.patch --]
[-- Type: text/x-diff, Size: 2035 bytes --]

From 269faa44ec18bb63c61ecba4cb232ceb0e46cd10 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@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


[-- Attachment #3: 0002-Improve-documentation-of-org-agenda-skip.patch --]
[-- Type: text/x-diff, Size: 3873 bytes --]

From f0af8f8e68e3953455c7ef5d08651da39ef86a01 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 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


[-- Attachment #4: 0003-Improve-documentation-of-org-kill-line.patch --]
[-- Type: text/x-diff, Size: 2108 bytes --]

From 2ac3989b3b1b03549df72ef955f0c49b2f62ebec Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@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

Re: [PATCH] Three documentation patches

[Ihor Radchenko]

Stefan Kangas <stefankangas@gmail.com> writes:

> Please find attached three separate documentation patches.

Thanks!
The patches look good, but I am unable to apply them onto current main:

128 git … am --3way -- /tmp/0002-Improve-documentation-of-org-agenda-skip.patch
Applying: Improve documentation of org-agenda-skip-*
error: sha1 information is lacking or useless (lisp/org-agenda.el).
error: could not build fake ancestor
Patch failed at 0001 Improve documentation of org-agenda-skip-*
hint: Use 'git am --show-current-patch=diff' to see the failed patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [PATCH] Three documentation patches

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 244 bytes --]

Ihor Radchenko <yantar92@gmail.com> writes:

> The patches look good, but I am unable to apply them onto current main:

Hmm, strange.  I've rebased on top of current main, and I'm resending
the resulting patches here.  I hope they work better.

[-- Attachment #2: 0001-Add-crossreference-to-org-stuck-projects-docstring.patch --]
[-- Type: text/x-diff, Size: 2035 bytes --]

From ffd00c1272dd876f64c9ef930d19988b6da5c2a3 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@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 e5df768ff..5b8133e81 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


[-- Attachment #3: 0002-Improve-documentation-of-org-agenda-skip.patch --]
[-- Type: text/x-diff, Size: 3858 bytes --]

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


[-- Attachment #4: 0003-Improve-documentation-of-org-kill-line.patch --]
[-- Type: text/x-diff, Size: 2108 bytes --]

From e3c2d0a979cff7077fe730b744fb18f08558cd11 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@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 537ad1487..075b6397f 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)
 
@@ -19970,7 +19972,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

Re: [PATCH] Three documentation patches

[Ihor Radchenko]

Stefan Kangas <stefankangas@gmail.com> writes:

> Ihor Radchenko <yantar92@gmail.com> writes:
>
>> The patches look good, but I am unable to apply them onto current main:
>
> Hmm, strange.  I've rebased on top of current main, and I'm resending
> the resulting patches here.  I hope they work better.

This time everything applies like a charm.
Thanks!

Applied onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=101280aa66baec74e36deaeac403cbcbb3c72be8
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=e28e3aaabba696444cf4f8243034602bc5824dc1
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=0b67b9f64f4fdba52398a729a76e18b6051401b4


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>