Re: Bug: Docstrings of =org-agenda-todo-ignore-with-date= and =org-agenda-todo-ignore-timestamp= unclear [9.2 (release_9.2-215-g5b39d8 @ /home/mbork/others-works/emacs/org-mode/lisp/)]

[Marcin Borkowski <mbork@mbork.pl>]

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


On 2019-06-19, at 21:19, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

> Hello,
>
> Marcin Borkowski <mbork@mbork.pl> writes:
>
>> The docstrings of =org-agenda-todo-ignore-with-date= and
>> =org-agenda-todo-ignore-timestamp= do not really tell what these
>> settings are doing.  They should (imho) emphasize that the former just
>> omits from the global todo list all entries with at least one active
>> timestamp (in the hedaline or the body), and the latter checks the first
>> active timestamp which is not SCHEDULED or DEADLINE and compares it to
>> today's date.
>>
>> It could also be mentioned in the manual.
>>
>> I have GNU papers for Emacs signed.  If this is enough, I'd be happy to
>> submit a patch.  If so, what would be better: to patch only the
>> docstrings or the docstrings and the manual.
>
> I would say the latter. Thank you.

I only patched the doctsrings for now.  If this is fine, I'll do
a similar thing in the manual.

WDYT?

-- 
Marcin Borkowski
http://mbork.pl

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Make-two-docstrings-more-clear.patch --]
[-- Type: text/x-patch; size=1.79KiB, Size: 1833 bytes --]

From d5a1c1ff3a9a7ccbf2765332971973b2c4233e16 Mon Sep 17 00:00:00 2001
From: Marcin Borkowski <mbork@mbork.pl>
Date: Sun, 23 Jun 2019 13:22:04 +0200
Subject: [PATCH] Make two docstrings more clear

The docstrings of `org-agenda-todo-ignore-with-date` and
`org-agenda-todo-ignore-timestamp` were not very clear.  Now they are
better.
---
 lisp/org-agenda.el | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index fbf520c5e..daf51601d 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -690,9 +690,10 @@ potentially much shorter TODO lists."
   "Non-nil means don't show entries with a date in the global todo list.
 You can use this if you prefer to mark mere appointments with a TODO keyword,
 but don't want them to show up in the TODO list.
-When this is set, it also covers deadlines and scheduled items, the settings
-of `org-agenda-todo-ignore-scheduled' and `org-agenda-todo-ignore-deadlines'
-will be ignored.
+When this is set, it also covers deadlines and scheduled items
+(more precisely, every entry with at least one active timestamp will be ignored),
+the settings of `org-agenda-todo-ignore-scheduled'
+and `org-agenda-todo-ignore-deadlines' will be ignored.
 See also the variable `org-agenda-tags-todo-honor-ignore-options'."
   :group 'org-agenda-skip
   :group 'org-agenda-todo-list
@@ -700,6 +701,9 @@ See also the variable `org-agenda-tags-todo-honor-ignore-options'."
 
 (defcustom org-agenda-todo-ignore-timestamp nil
   "Non-nil means don't show entries with a timestamp.
+If this variable is non-nil, Org agenda looks at the first active
+timestamp in the entry which is neither a DEADLINE nor
+a SCHEDULED timestamp and compares it to \"today\".
 This applies when creating the global todo list.
 Valid values are:
 
-- 
2.22.0