Claude
d754dd4ffc
The recent feature changes introduced part-of-period progression with new granularity levels (part-of-month, part-of-season, part-of-year, year), but the README still showed the old 9 levels including an incorrect "Week number" entry. Updated to show all 11 levels with correct examples and added configuration examples for the new granularity options.
179 lines
4.6 KiB
Org Mode
179 lines
4.6 KiB
Org Mode
#+TITLE: fuzzy-clock.el
|
|
#+AUTHOR: Fuzzy Clock Contributors
|
|
|
|
* What is this?
|
|
|
|
Fuzzy Clock displays time in Emacs the way humans naturally think about it.
|
|
|
|
Instead of =14:32=, you see "Half past two".
|
|
|
|
Instead of obsessing over every minute, you see "Afternoon".
|
|
|
|
* Quick Start
|
|
|
|
#+begin_src emacs-lisp
|
|
;; Load and enable
|
|
(require 'fuzzy-clock)
|
|
(fuzzy-clock-mode 1)
|
|
#+end_src
|
|
|
|
Look at your mode-line. You should see something like "Three o'clock" or "Afternoon".
|
|
|
|
* Why?
|
|
|
|
Humans don't think in precise time. We think in approximations:
|
|
- "Let's meet around three"
|
|
- "I'll be there in half an hour"
|
|
- "See you this afternoon"
|
|
|
|
Fuzzy Clock eliminates the mental overhead of constantly converting =14:32= to "about half past two". It shows time the way you already think about it.
|
|
|
|
More importantly, it changes your relationship with time. When your mode-line says "Afternoon" instead of =14:32=, you stop obsessing over every passing minute.
|
|
|
|
* Fuzziness Levels
|
|
|
|
Fuzzy Clock supports 11 levels of fuzziness, from precise to very abstract:
|
|
|
|
| Level | Type | Example |
|
|
|-------+-------------------+---------------------------|
|
|
| 1 | Every 5 minutes | "Quarter past three" |
|
|
| 2 | Every 15 min | "Half past three" |
|
|
| 3 | Half hour | "Three o'clock" |
|
|
| 4 | Hour (default) | "Three o'clock" |
|
|
| 5 | Part of day | "Afternoon" |
|
|
| 6 | Day of week | "Tuesday" |
|
|
| 7 | Part of month | "Early October" |
|
|
| 8 | Month | "October" |
|
|
| 9 | Part of season | "Early Fall" |
|
|
| 10 | Part of year | "Early 2025" |
|
|
| 11 | Year | "2025" |
|
|
|
|
Choose your fuzziness level:
|
|
|
|
#+begin_src emacs-lisp
|
|
;; Maximum precision (still natural language)
|
|
(setq fuzzy-clock-fuzziness 'five-minutes)
|
|
|
|
;; Default: hour precision
|
|
(setq fuzzy-clock-fuzziness 'hour)
|
|
|
|
;; Deep focus: eliminate time anxiety
|
|
(setq fuzzy-clock-fuzziness 'part-of-day)
|
|
|
|
;; Weekly planning
|
|
(setq fuzzy-clock-fuzziness 'day-of-week)
|
|
|
|
;; Monthly view
|
|
(setq fuzzy-clock-fuzziness 'part-of-month)
|
|
|
|
;; Seasonal perspective
|
|
(setq fuzzy-clock-fuzziness 'part-of-season)
|
|
|
|
;; Long-term planning
|
|
(setq fuzzy-clock-fuzziness 'part-of-year)
|
|
#+end_src
|
|
|
|
* Configuration
|
|
|
|
Basic configuration:
|
|
|
|
#+begin_src emacs-lisp
|
|
(require 'fuzzy-clock)
|
|
|
|
;; Set fuzziness level (default: 'hour)
|
|
(setq fuzzy-clock-fuzziness 'hour)
|
|
|
|
;; Set update interval in seconds (default: 60)
|
|
(setq fuzzy-clock-update-interval 60)
|
|
|
|
;; Enable mode-line display
|
|
(fuzzy-clock-mode 1)
|
|
#+end_src
|
|
|
|
Recommended for deep focus:
|
|
|
|
#+begin_src emacs-lisp
|
|
(setq fuzzy-clock-fuzziness 'part-of-day)
|
|
(setq fuzzy-clock-update-interval 3600) ; Update once per hour
|
|
(fuzzy-clock-mode 1)
|
|
#+end_src
|
|
|
|
* Commands
|
|
|
|
| Command | Description |
|
|
|------------------------------+---------------------------------------|
|
|
| =M-x fuzzy-clock-mode= | Toggle fuzzy clock in mode-line |
|
|
| =M-x fuzzy-clock-show= | Show fuzzy time once in minibuffer |
|
|
| =M-x fuzzy-clock-display-buffer= | Show fuzzy time in dedicated buffer |
|
|
|
|
* Customization
|
|
|
|
Use Emacs' built-in customization interface:
|
|
|
|
#+begin_src emacs-lisp
|
|
M-x customize-group RET fuzzy-clock RET
|
|
#+end_src
|
|
|
|
Two variables:
|
|
- ~fuzzy-clock-fuzziness~ — Fuzziness level
|
|
- ~fuzzy-clock-update-interval~ — Update frequency in seconds
|
|
|
|
* Documentation
|
|
|
|
For comprehensive documentation including:
|
|
- The philosophy of fuzzy time
|
|
- Detailed explanation of each fuzziness level
|
|
- When to use each level
|
|
- Advanced configurations
|
|
- Complete API reference
|
|
|
|
See: [[file:doc/fuzzy-clock.org][doc/fuzzy-clock.org]]
|
|
|
|
The documentation follows Steve Losh's "teach-don't-tell" philosophy. It will teach you how to *think* about fuzzy time, not just how to configure it.
|
|
|
|
* Installation
|
|
|
|
** Manual Installation
|
|
|
|
1. Clone this repository or download ~fuzzy-clock.el~
|
|
2. Add to your ~load-path~:
|
|
|
|
#+begin_src emacs-lisp
|
|
(add-to-list 'load-path "/path/to/fuzzy-clock.el")
|
|
(require 'fuzzy-clock)
|
|
#+end_src
|
|
|
|
** Package Manager
|
|
|
|
Not yet published to MELPA. Manual installation required.
|
|
|
|
* Requirements
|
|
|
|
- Emacs 24.4 or later
|
|
- No external dependencies
|
|
|
|
* Testing
|
|
|
|
Tests use Buttercup via Eldev:
|
|
|
|
#+begin_src sh
|
|
# Run all tests
|
|
eldev test
|
|
#+end_src
|
|
|
|
* License
|
|
|
|
See LICENSE file.
|
|
|
|
* Inspiration
|
|
|
|
Inspired by the KDE fuzzy clock widget.
|
|
|
|
* Philosophy
|
|
|
|
This package embodies a simple idea: *software should adapt to humans, not the other way around*.
|
|
|
|
We evolved to think about time in approximate, contextual terms. Digital clocks force precision we don't need and can't use.
|
|
|
|
Fuzzy Clock lets you be human again.
|