From b88e9c139d442e0b3f15551ce31f09fc7478f3b2 Mon Sep 17 00:00:00 2001 From: Historia Date: Tue, 25 Jun 2024 17:38:45 -0400 Subject: Initial commit --- README.md | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 108 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index f21bfb0..0c2a7ae 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,110 @@ # then -Minimalist, single text file calendar inspired by 'when' \ No newline at end of file +then is a plain text calendar program inspired by [When](https://www.lightandmatter.com/when/when.html). + +## Goals +- Recurring events + +## Non-goals +- One line per event/day (might change this to how Remind works?) +- Nearest-weekday dates (e.g. the 'c' variable in `when`) +- Conditional recurrence like "Garbage day is every Tuesday except on Holidays" (I suggest [Remind](https://dianne.skoll.ca/projects/remind/) for this) + +# `.then` file syntax + +``` +# COMMENT +DATE, EVENT +- DETAILS +``` + +- Lines beginning with `#` are comments used to annotate or group events together. +- Lines beginning with `-` are additional details attached to the above event. +- Blank lines are ignored. +- Otherwise, a line is an event. Everything before the first comma is interpreted as the date. +- Parameters in the date can be written in any order, whitespace delimited: + +1. 4 digts is the year +2. A month can be written as a full word (January) or 3-character abbreviation (Jan) +3. Days can be full words or common abbreviations (R, Th, Thu, Thur, or Thurs, or Thursday are all acceptable) +4. NN:NN is the time. An end time can be given too as NN:NN-NN:NN with no space. +5. Nw is the Nth set of 7 days in a month, e.g. `2w`. +6. Nlw is the Nth-from-last set of 7 days in a month, e.g. `2lw` + +``` +# Simple Examples + +2025 Jan 1 00:00-03:00, Work party +2025 Jan 1 04:00, Go to bed +Jan 1, New Year's Day (Jan 1 every year) +1, Mortgage due (1st of every month) + + +# `w` and `lw` parameters + +May 2w Sun, Mother's Day (Second Sunday of May) +May 1lw Mon, Memorial Day (Last Monday of May) + + +# Logical Operators (`|` or, `!` not, `and` is implied by whitespace) + +1 | 15, 1st OR 15th of month +Fri !(Dec 25), Every Friday, NOT December 25 +1 2, 1st AND 2nd (i.e. never) + +# Modified Julian Date Logic (`j` and `%`) +# We have to work on the syntax + +!(j%14-5), Every other Saturday + + +# Details (Any lines prepended with - are attached to the above event) + +2025 Jan 5 16:00, Doctor's Appointment +- 123 Gentoo Road, San Francisco, CA 12345 +- Dr. Elias Berkins, +1 (555)-123-1234 +``` + +Lines prefixed with `#` are comments and can be used to organize events into groups. When sorting events, all events under a comment will stay under that same comment. + + +# Why would I use this? + +Calendars are some of the most integrated (yet privacy invasive) productivity applications. If you use Outlook or Google Calendar to share meetings and availability across a team or family, an offline, DIY-synced, text file with arcane syntax is not a suitable replacement. + +For my personal calendar I used to use [Proton Calendar](https://proton.me/calendar), which by design is a hassle to share/export/automate. Rather than try to wrangle a third party calendar, I'm reinventing the wheel. + +## Why would I use this *over When*? + +I really like When (the Perl program) and then is objectively less powerful because it omits variables I never use. This let's me express days in a simpler syntax. + +1. Parameter types are inferred. The only 4-digit `%d%d%d%d` string that can appear in a date is the year. `y=1984` in `when` is simplified to `1984` in `then`. This is possible by omiting the `e` (Easter), `z` (Day of year), and `c` (Nearest weekday) variables, and changing `a=1` and `b=2` to `1W` and `2LW`. +2. The `&` logical operator is implied by whitespace. `m=jan & d=1` in `when` is simplified to `Jan 1` in `then`. + +In short, I think it looks nicer: + +when: `m=dec & d=25, Christmas` or `* Dec 25, Christmas` +then: `Dec 25, Christmas` + +when: `m=sep & w=mon & a=1, Labor Day` +then: `Sep Mon 1W, Labor Day` + + +# Alternatives + +If you're interested in text file based calendars, the three GOATs are: + +- [When](https://www.lightandmatter.com/when/when.html) - IMO, the simplest terminal calendar that's flexible enough for real world use. +- [Remind](https://dianne.skoll.ca/projects/remind/) - A **VERY** flexible, programmable calendar format. I can't imagine a scheduling case you couldn't cover. [(Better overview here.)](https://blog.thechases.com/posts/remind/) +- [Org Mode](https://orgmode.org) - The most flexible and expansive productivity playground for text (warning: endless time sink). + +## See Also + +- [Emacs Diary](https://www.gnu.org/software/emacs/manual/html_node/emacs/Format-of-Diary-File.html) - A single agenda/diary file. +- [Plain Text Personal Organizer](https://danlucraft.com/blog/2008/04/plain-text-organizer/) +- [Calendar.txt](https://terokarvinen.com/2021/calendar-txt/) - A one-day per line text calendar format inspired by [todo.txt](https://todotxt.org/). Very simple but high maintenence due to lack of repeating events, etc. +- Featureful TUI calendar/productivity apps like [Calcurse](https://calcurse.org/), [calcure](https://github.com/anufrievroman/calcure), [khal](https://github.com/pimutils/khal), and maybe [Taskwarrior](https://taskwarrior.org/). Often it's preferable to manage appointments via the program itself rather than directly editing a text file. + +# License + +MIT -- cgit v1.2.3