Work-timers

Why: My use case

work-timer has in mind users who need to regulate how often they work and take breaks. The most common cases would be having large amounts of self-directed work time, either from regularly having a capacity as a student or have flexible work schedules.

My personal use case is thus. I am currently a university student. I have been using work-timer for a few months now, and it has been a tremendous help for me as an automatic means for telling me how long I should work and how long I should take a break—important for staying productive on the days I’m tired and not overworking myself on other days.

Usage

Advantage: history

Mimicking org-pomodoro

Mimicking org-pomodoro-third-time

Advanced configuration

Internals

Relevant variables and functions

Example configuration

Suggestions

Inspirations and related packages

• Org-pomodoro-third-time: Adapt org-pomodoro to implement the Third Time system (mention differences tk)
• Org-timer: built-in org-mode package.
• Tmr: Protesilaos’s timer package.

Comparison to org-pomodoro

Differences

• work-timer supports arbitrarily complex ways to set the duration of timers. For instance, built-in is support determining timer duration based on the history of ran timers and how much time the previous was overran by.
• work-timer supports seamless user configuration by means of work-timer-work-duration-function and work-timer-break-duration-function.
  • work-timer also has more built-in support for useful ways to determine break and work durations beyond Pomodoro-style timers, e.g., work-timer-fractional-*-duration.
• work-timer offers work-timer-modify to modify the parameters (e.g. running time, duration) of the currently running timer.
• work-timer supports arbitrary timer types (for more flexibility than just work-break cycles).
• work-timer supports manual entry of timer duration when desired.
• work-timer supports pausing of timers.
• work-timer generally has cleaner code logic and more points of entry for users, making it more extensible, I argue. For example, work-timer-history and the several variables that hold information for the current timer are accessible for whatever the user needs, whether it be defining their own work-timer-work-duration-function or adding to work-timer-modify.

Similarities

• Overrun timers.
• Mode line indictor.
• Pomodoro-style timers.

Tips and tricks

Saving current timer across Emacs sessions with savehist

Sometimes you have a running timer and Emacs crashes. Or perhaps you’d like to save the work-timer-history for one reason or another. work-timer simply saves the current work timer information in variables, so you can save these variables across Emacs sessions via savehist. work-timer is configured such that starting a new timer (via work-timer-start or work-timer-start-or-finish) will use the already set variable values, effectively resuming the timer.

;; Save timer variables to resume timer across Emacs sessions
(dolist (var '(work-timer-start-time
               work-timer-duration
               work-timer-type
               work-timer-pauses
               work-timer-history))
  (add-to-list 'savehist-additional-variables var))

If you do not want to save the timer history, feel free to remove work-timer-history. (It might be useful to know that work-timer-end allows from wiping the entire history or just the current timer.)