When I adopted Emacs in July of 2000, I hunkered down to learn the
keybindings. But after I learned the basics1 I started
to RTFM (C-h r), and I was instantly drawn to the
Calendar/Diary2 node, which I consider to be an
underappreciated Emacs built-in, and, therefore, the topic of Emacs
Carnival for June 2026.
Back then I mistook "diary" to mean a blank-page-confidant into
which we write our thoughts, fears, ambitions or even just what we
had for dinner last night. At that time I'd been writing in
a journal for about 24 years (yes, since 1976, on and off), so my head
swelled with ideas of using Emacs for a revamped computerized
version. I imagined being able to forward-search-regexp
in order
to find, for example, that weird dream I wrote about in which I
caught a toad that was hopping around the kitchen and then turned
into a hot coal sizzling in my hand...
I used diary-block functions to date my entries and
organize the content. I ended up making four such entries from 2003
to 2004. But each day following the entry, M-x diary
would display a nearly blank buffer, showing only the day's date at
the top followed by a line of equal signs and perhaps a holiday.
Where did yesterday's entry go?! It was disconcerting that those
words "vanished" into thin air magnetic film or
silicon.
Today, however, I appreciate the simplicity of that approach -- a
clean slate sans distractions. But back then I was accustomed to
seeing a vast amount of my writing, which fed my ego.
But that's not all there is to appreciate. There are several
functions that can be used for "an entry" in addition to
diary-block, such as diary-anniversary, diary-cyclic, diary-float or even just a simple line that begins with a date and a brief note. This is not an all-inclusive list.
Every fancy diary buffer can show local time of sunrise and sunset;
to do this, include diary-sunrise-sunset in the diary file.
Include diary-lunar-phases to show one of the four
phases of the moon when one is active on that day; the
local time of that moon phase will be included.
What follows is an abbreviated and edited listing of my diary
files. Note how I've structured diary into a hierarchy
using include statements.
2026-06-17 02:25 GMT Important updates: First, you'll need to modify two hook variables in order
for the include statements to work. Please see
the help
for Fancy Diary Display. I also "use the normal hook
diary-list-entries-hook to sort each day's diary
entries by their time of day," which is described at the top of that
page. Second, specify the full path to the included files.
I've modified the two include statements to add the "~/" path. This
is needed only if you want to press TAB on the item in the Agenda in
order to focus the diary entry.
The beauty of this is that these events will show up in Org Agenda
at the appropriate times when org-agenda-include-diary
is non-nil.
Four examples are shown below. Here are some things to note:
- The content that's derived from the diary file has "Diary" for value of CATEGORY.
- The Sunrise / Sunset lines are supposed to show the time of
each occurance. However, the time for Sunrise isn't displayed;
rather, it's indicated by its position on the time grid. The times for both the New Moon and the Solar Eclipse are indicated by the time grid, as well, and are expected to peak at 13:38 in my area. That's something to look faroward to!
- Sometimes I include links in my headings. In this case I can
follow a link to the credit card website to pay the Visa
card.
- Even a link in the dairy file will be rendered
in the Agenda properly, as shown in the reference for Richard
Stallman's birthday.
file listing: diary
# -*- mode: diary -*-
#include "~/diary-anniversaries-property"
#include "~/diary-birthdays-friends"
%%(diary-sunrise-sunset)
%%(diary-lunar-phases)
%%(diary-remind '(diary-anniversary 3 16 1953) 14) [[https://html.duckduckgo.com/html/?q=Richard+Stallman+birthday][Richard Stallman's birthday]] in 14 days
%%(diary-block 6 21 2004 6 21 2004) The summer solstice. I
always take time to observe the position of the sun on this
day, especially in the morning and evening. Sunrise was at
5:16am and sunset will be at 8:29pm. From today onward, the
days will be getting shorter. At first it will be
imperceptible, but in September, it'll be quite noticeable.
file listing: diary-anniversaries-property
# -*- mode: diary -*-
# Recurring Property events or records
%%(diary-remind '(diary-date 7 3 '(2023 2026 2029)) 30) Car Registration is due
%%(diary-anniversary 8 12 2022) Kitchen Cabinets Painted %d Years Ago
file listing: diary-birthdays-friends
# -*- mode: diary -*-
# Birthdays of friends
%%(diary-anniversary 8 13) Bucky Thorndike Miller's Birthday (Does Dave still have his guitar amp?)
%%(diary-anniversary 2 13 1966) Ben's %d%s Birthday
Day-agenda (W11):
Tuesday 16 March 2027
Diary: 7:03 ┄┄┄┄┄ Sunrise (EDT), sunset 18:58 (EDT) at Home (11:54 hrs daylight)
8:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
BILLS: 9:00 ┄┄┄┄┄ Deadline: TODO Visa Card LINK :Bills::Credit:
10:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
12:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
14:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
16:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
18:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
20:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
Diary: Richard Stallman's birthday in 14 days
Day-agenda (W23):
Wednesday 3 June 2026
Diary: 5:19 ┄┄┄┄┄ Sunrise (EDT), sunset 20:20 (EDT) at Home (15:00 hrs daylight)
8:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
10:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
12:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
14:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
16:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
18:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
20:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
Diary: Reminder: Only 30 days until Car Registration is due
Day-agenda (W33):
Wednesday 12 August 2026
Diary: 5:58 ┄┄┄┄┄ Sunrise (EDT), sunset 19:54 (EDT) at Home (13:56 hrs daylight)
8:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
9:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
10:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
12:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
Diary: 13:38 ┄┄┄┄┄ New Moon (EDT) ** Solar Eclipse **
14:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
16:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
18:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
20:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
Diary: Kitchen Cabinets Painted 4 Years Ago
Day-agenda (W32):
Saturday 13 August 2022
Diary: 5:59 ┄┄┄┄┄ Sunrise (EDT), sunset 19:53 (EDT) at Home (13:53 hrs daylight)
8:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
10:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
12:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
14:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
16:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
18:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
20:00 ┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
Diary: Bucky Thorndike Miller's Birthday (Does Dave still have his guitar amp?)
1My requirements (the basics) for a text editor were:
- column editing
- keystroke recording and playback
- regular expression search and replace
- undo
- support multiple files in multiple windows
2Calendar/Diary in the GNU Emacs Manual