* [PATCH] Three documentation patches
@ 2022-10-02 19:58 Stefan Kangas
2022-10-06 4:01 ` Ihor Radchenko
0 siblings, 1 reply; 4+ messages in thread
From: Stefan Kangas @ 2022-10-02 19:58 UTC (permalink / raw)
To: Org-mode
[-- 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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] Three documentation patches
2022-10-02 19:58 [PATCH] Three documentation patches Stefan Kangas
@ 2022-10-06 4:01 ` Ihor Radchenko
2022-10-06 4:23 ` Stefan Kangas
0 siblings, 1 reply; 4+ messages in thread
From: Ihor Radchenko @ 2022-10-06 4:01 UTC (permalink / raw)
To: Stefan Kangas; +Cc: Org-mode
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>
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] Three documentation patches
2022-10-06 4:01 ` Ihor Radchenko
@ 2022-10-06 4:23 ` Stefan Kangas
2022-10-07 3:49 ` Ihor Radchenko
0 siblings, 1 reply; 4+ messages in thread
From: Stefan Kangas @ 2022-10-06 4:23 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Org-mode
[-- 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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] Three documentation patches
2022-10-06 4:23 ` Stefan Kangas
@ 2022-10-07 3:49 ` Ihor Radchenko
0 siblings, 0 replies; 4+ messages in thread
From: Ihor Radchenko @ 2022-10-07 3:49 UTC (permalink / raw)
To: Stefan Kangas; +Cc: Org-mode
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>
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2022-10-07 3:49 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-10-02 19:58 [PATCH] Three documentation patches Stefan Kangas
2022-10-06 4:01 ` Ihor Radchenko
2022-10-06 4:23 ` Stefan Kangas
2022-10-07 3:49 ` Ihor Radchenko
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).