Ray on Emacs: Emacs Carnival: diary, Part 1

When I adopted Emacs in July of 2000, I hunkered down to learn the keybindings. But after I learned the basics¹ I started to RTFM (C-h r), and I was instantly drawn to the Calendar/Diary² 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.

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?)