Add org-postpone package

[j-cr]

Brief summary of what the package does

Postpone tasks in agenda buffers

This package allows you to postpone a scheduled entry, hiding it from the
agenda buffer for today. It is especially useful for habits (see chapter
"5.3.3 Tracking your habits" in the org manual).

Direct link to the package repository

https://github.com/j-cr/org-postpone

Your association with the package

Author/maintainer

Relevant communications with the upstream package maintainer

None needed

Checklist

Please confirm with x:

• The package is released under a GPL-Compatible Free Software License.
• I've read CONTRIBUTING.org
• I've used the latest version of package-lint to check for packaging issues, and addressed its feedback (package-lint is broken in melpa-stable, can't install)
• My elisp byte-compiles cleanly
• M-x checkdoc is happy with my docstrings (it complains about comments in my private functions - screw it! All the public docstring are fine)
• I've built and installed the package using the instructions in CONTRIBUTING.org
• I have confirmed some of these without doing them

[alphapapa]

Copying my comment from https://www.reddit.com/r/emacs/comments/dpjfci/postpone_tasks_esp_habits_till_tomorrow_in_the/.

I don't understand the purpose of this package. The readme says:

Note that it won’t be rescheduled (it’s only hidden from the agenda view), so tomorrow it will appear again as normal.

If the task were rescheduled for the next day, it would also appear in the agenda the next day. AFAIK, the only difference is that, with this package, the task would indicate that its scheduled date had passed x days earlier.

Of course, this is Emacs and Org, so you can do whatever you like, whatever fits your needs. But I feel like this package's rationale is based on a common misunderstanding of what DEADLINE and SCHEDULED dates are intended to mean in Org. From the Org manual: https://orgmode.org/manual/Deadlines-and-Scheduling.html

‘SCHEDULED’ Meaning: you are planning to start working on that task on the given date.

Important: Scheduling an item in Org mode should not be understood in the same way that we understand scheduling a meeting. Setting a date for a meeting is just a simple appointment, you should mark this entry with a simple plain timestamp, to get this item shown on the date where it applies. This is a frequent misunderstanding by Org users. In Org mode, scheduling means setting a date when you want to start working on an action item.

Also, there is already a built-in feature that postpones the display of tasks in the agenda:

If you want to delay the display of this task in the agenda, use SCHEDULED: <2004-12-25 Sat -2d>: the task is still scheduled on the 25th but will appear two days later.

That built-in feature seems to have the same effect as this package. But this package, rather than simply implementing a convenient interface to that functionality (e.g. a command that increments a timestamp's delay attribute), seems to reimplement the feature by using a :POSTPONED: property and an agenda skip function.

So why not use the built-in feature to accomplish the same effect?

---

Regarding the checklist:

package-lint is broken in melpa-stable, can't install

MELPA Stable is, unfortunately, not a viable solution for many cases. You should install package-lint from regular MELPA and use it. Or install it manually and use it. The tool saves the time of MELPA reviewers.

it complains about comments in my private functions - screw it! All the public docstring are fine

There are no private functions in Emacs Lisp. The -- convention is only a convention. It only communicates to users what functions are intended to be used from within the package's functions.

The purpose of docstrings is to aid users in understanding how a package works. All docstrings are important. So you should fix them according to the tool's feedback.

Upholding these standards upholds the quality of MELPA, which benefits everyone.

[j-cr]

So why not use the built-in feature to accomplish the same effect?

It's not the same effect, the package's purpose is to hide repeating tasks (e.g. habits) from today's view. I don't see how something like SCHEDULED: <2004-12-25 Sat -2d> can be used to achieve that (well, I guess technically it can be used as an alternative implementation, but that would be a very roundabout way to achieve the same effect). You can't reschedule the task either since it will mess up the periodic scheduling. To me it sounds like you don't use habits or repeating tasks, maybe that's the reason of misunderstanding?

There are no private functions in Emacs Lisp. The -- convention is only a convention.

Sure, I know that and I assumed MELPA maintainers know that too so it would be clear what I meant.

So you should fix them according to the tool's feedback.

Well, okay, I just removed the argument from that function since it currently isn't being used anyway.

Or install it manually and use it.

Okay, I did it and I got 3 issues, though I'm not sure what would be the best way to proceed here:

1:61: warning: You should depend on (emacs "24") if you need lexical-binding.
45:12: warning: Replace deprecated `cl' with `cl-lib'.  The `cl-libify' package can help with this.

This package is based on the code from org-agenda (and obviously depends on it), which uses cl, so getting rid of cl won't achieve anything (but has a certain potential to break something). Similarly, I don't need lexical-binding and thus see no reason for this not to work on emacs <24. So, can we ignore those warnings?

57:0: error: "org-agenda-skip-if-postponed" doesn't start with package's prefix "org-postpone".

Here my idea was to be in line with other org-agenda-skip-* functions, but I guess I can rename it as well.

[alphapapa]

You can't reschedule the task either since it will mess up the periodic scheduling. To me it sounds like you don't use habits or repeating tasks, maybe that's the reason of misunderstanding?

Of course I use them.

I think part of the issue here is that there are several different ways that entries can appear in the agenda:

• Entries with an active timestamp anywhere in the entry
• Entries that have a deadline
• Entries that are SCHEDULED
• Entries that are habits

As well, any of those types may have repeating timestamps, and certain ones may have warning periods or delay periods which affect their display in the agenda, which is what your package seems intended to affect. So it's not clear when this package should be used instead of the aforementioned, built-in features.

So it would be good if it were more clearly explained when the package is appropriate to use, and how it interacts with and compares to the similar, built-in features.

So why not use the built-in feature to accomplish the same effect?

It's not the same effect, the package's purpose is to hide repeating tasks (e.g. habits) from today's view. I don't see how something like SCHEDULED: <2004-12-25 Sat -2d> can be used to achieve that (well, I guess technically it can be used as an alternative implementation, but that would be a very roundabout way to achieve the same effect).

Why would that be a roundabout way? For SCHEDULED entries, that's exactly what the delay cookie is for. The manual says:

If you want to delay the display of this task in the agenda, use SCHEDULED: <2004-12-25 Sat -2d>: the task is still scheduled on the 25th but will appear two days later. In case the task contains a repeater, the delay is considered to affect all occurrences; if you want the delay to only affect the first scheduled occurrence of the task, use ‘--2d’ instead. See org-scheduled-delay-days and org-agenda-skip-scheduled-delay-if-deadline for details on how to control this globally or per agenda.

So maybe your package is more suitable for other types of entries, in which case, again, more documentation is needed to guide users.

Or install it manually and use it.

Okay, I did it and I got 3 issues, though I'm not sure what would be the best way to proceed here:

1:61: warning: You should depend on (emacs "24") if you need lexical-binding.
45:12: warning: Replace deprecated `cl' with `cl-lib'.  The `cl-libify' package can help with this.

This package is based on the code from org-agenda (and obviously depends on it), which uses cl, so getting rid of cl won't achieve anything (but has a certain potential to break something). Similarly, I don't need lexical-binding and thus see no reason for this not to work on emacs <24. So, can we ignore those warnings?

Just do what it says:

1. Depend on Emacs 24 as a minimum.
2. (require 'cl-lib).

Emacs 24.1 was released 7 years ago. I doubt your code would be compatible with Emacs versions older than that, and I doubt anyone who's using 23.4 will be attempting to use it.

You should always use lexical binding in new packages: https://github.com/alphapapa/emacs-package-dev-handbook#lexical-binding-1

57:0: error: "org-agenda-skip-if-postponed" doesn't start with package's prefix "org-postpone".

Here my idea was to be in line with other org-agenda-skip-* functions, but I guess I can rename it as well.

This is a strict MELPA requirement.

[j-cr]

Just do what it says

Okay, all pushed.

So it would be good if it were more clearly explained when the package is appropriate to use, and how it interacts with and compares to the similar, built-in features.

I'd be glad to add more documentation to the readme, but to be honest I don't understand what exactly isn't clear right now and how I can achieve the same effect with built-in features. Maybe I don't understand how some of them work, and you can clearify how would you use them to achieve the same effect.

Consider an example: I have a task that is SCHEDULED: <2019-11-01 Fri .+1d/5d>, and let's say today is 2019-11-03. I don't feel like doing this task today, so I want to hide it from my main "things to do today" agenda view. I can't reschedule the task to another date, since that will mess up my habit tracking and scheduling (and I don't want to reschedule it, I just want to hide it from a single agenda view). In order to use the -n cookie, I have to compare the current date with the scheduled date for the task, and insert the appropriate number of days (which is a very roundabout way to achieve the "hide an item from an agenda view" effect, even if implemented programmatically). Also, it would hide the task from all agenda views, not just my main "next things to do today" one, so I would have to do some extra work to make it visible somehow in other agenda views (e.g. in my "daily review" agenda view I may want to see all the tasks that were scheduled for today but weren't done so I can review how productive or lazy I was today). In fact all I want to do is to hide (filter) specific tasks from a specific agenda view (without rescheduling them or affecting them in any other way), which is exactly what org-agenda-skip-function is there for.

So, to sum it up, I don't really understand what's wrong with this implementation and it's not immediately obvious to me how it could be made simpler, and also I don't understand how the same effect could be achieved with built-in scheduling tools, and also what exactly is currently confusing about the purpose of this package and how I can clarify it. Of course I'm not saying that you or anyone else have to use it if built-in mechanisms work just fine for your workflow, but at the same time to me it seems like a rather basic feature that is nice to have.

[riscy]

In your commentary, I wonder if you capitalized one word:

This package allows you to postpone a "SCHEDULED" entry

because even the org-mode documents have to strive to clarify what "scheduling" means in org-world.

Re: the discussion above, I'm less versed in org mode than both parties. It feels like the --1d SCHEDULE syntax already accomplishes this, but I can see @j-cr's point that its use is not terribly ergonomic.

@j-cr, this text:

Consider an example: I have a task that is SCHEDULED: <2019-11-01 Fri .+1d/5d>

feels like it should be added to your documentation in some form - your README and Commentary do feel a bit sparse. Especially the part where you say: "hide (filter) specific tasks from a specific agenda view".

Should org-postpone-entry-until-tomorrow be autoloaded? Should it be renamed (or have an alias) called org-postpone for brevity and ease of use?

[tarsius]

Closing due to inactivity.
Let us know when you are ready so that we can reopen and finish the review.