diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 223 |
1 files changed, 94 insertions, 129 deletions
@@ -2,8 +2,7 @@ Soon is a minimalist, text file based, CLI calendar inspired by [When](https://www.lightandmatter.com/when/when.html). It has simple, concise syntax but supports recurring cases more complex than most calendars. -- Schedule events in a text file -- Concise syntax for recurring cases and date ranges +- Schedule events in a text file with concise syntax - Group, sort, comment, and columnize events to keep files neat - Add multiple lines of details to events - Archive events to remove them from your schedule (e.g. paid bill) @@ -13,89 +12,70 @@ Soon is a minimalist, text file based, CLI calendar inspired by [When](https://w In terms of features and complexity, Soon lies between [When](https://www.lightandmatter.com/when/when.html) and [Remind](https://dianne.skoll.ca/projects/remind/) but aims to be less verbose than either. -# Arguments +# Quick Start -``` -Usage: soon [options] - -Options: --a print agenda (default behavior if no options) --c print reference calendar --t print todos --e open default calendar file in $EDITOR --i open TUI in interactive mode to schedule/archive events --w, -m, -y print agenda for upcoming week, month, or year --j print the modified julian day --d print today's date --p, --past=DAYS days in past to print agenda (default: 1) --f, --future=DAYS days in future to print agenda (default: 14) --h, --help show this help --v, --version print version - -Combine commands to get output in a certain order. -`soon -ca` prints a calendar followed by an agenda. -`soon -at` prints an agenda followed by todos. - -Check the docs at https://codeberg.org/historia/soon -``` +1. Download Soon and copy it into you PATH (e.g. /usr/local/bin) -# .soon file syntax +2. Run `soon -e`. This will generate a config and calendar file under $XDG_CONFIG_HOME/soon and open the calendar file in your editor. + +3. Add some events and todos to your calendar file. ``` -# COMMENT -DATE, EVENT -- DETAILS -``` +# Simple Dates +2025 Jul 17, Single day event +Fri 8pm, Every Friday at 8pm +Jan 1, Jan 1 every year +Tue, Every Tuesday +1, 1st of every month -- 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. +# Logic Conditions +Mon Fri, Mondays and Fridays +Fri !13, Every Friday except the 13th -Otherwise, a line is an event. Everything before the first comma is interpreted as the date, which is a list of conditions separated by whitespace. Parameters can be written in any order. Short or long month and weekday names can be used. +# Ranges +(Jul 7 2024)-(Jul 13 2024), Shark Week +July 7-13 2024, Shark Week -## Example Syntax +# Uncommon recurrence patterns +J%3, Every third day (See: Advanced Recurrence) +Fri 1W, First Friday of the month +# Todos start with a hyphen +- Buy milk +- Read War and Peace +- This todo has a parsable deadline + + Due: Aug 15 2025 ``` -# Common dates and recurrence -2025 Jul 17, Hike Mt. Fuji -Jan 1, New Year's Day (Jan 1 every year) -Tue, Taco night (Every Tuesday) -1, Mortgage due (1st of every month) -, Journal (Every day) +4. Run `soon` to see your agenda. With no options it will show you the next 14 days of events as well as your todos and deadlines. -# Times +5. Run `soon -i` to start interactive mode and archive events or todos. Select events/todos with HJKL and archive them with Space. Esc to exit. -2025 Jan 1 00:00-03:00, Work party -2025 Jan 1 04:00, Go to bed -20:00 Fri, Friday Night Magic (Every Friday at 8pm) -9am, Coffee (Every day at 9am) +# .soon file syntax -# Logic and Date Ranges +Each event is a line with date conditions followed by `,` and a description. -Mon Wed Fri, Submit TPS Report (Every Mon, Wed, or Fri) -Fri !13, Every Friday except the 13th -July 7-13 2024, Shark Week -(Jun 25 2025)-(Jul 4 2025), Japan Trip +Lines starting with `-` are todos -# Uncommon recurrence patterns +Lines starting with `+` are attached to the above event/todo to add details or deadlines. -J%3, Every third day -Fri 1W, First Friday of the month +Lines starting with `#` are comments and ignored, as are blank lines. -# Combine multiple features for complex recurrence +## Date Condition Logic -Jul 10-19 2025 J%3-2, This event repeats July 10, 13, 16, 19 -``` +Years, months, weekdays, days can be listed in any order. Months and weekdays can use full names or 3 letter short names. -## Adding details to events +Conditions of different types (e.g. a month and day) all have to be satified. -Any line starting with a `+` is attached to the nearest above event. This can be used for details about an event if you don't want to put everything on one line. +If multiple conditions of the same type exist (e.g. two days), only one has to be satisfied. + +Prepend `!` to any condition to mean NOT. ``` -2025 Jan 5 16:00, Doctor's Appointment -+ 123 Gentoo Road, San Francisco, CA 12345 -+ Dr. Elias Berkins, +1 (555)-123-1234 +Jan 1, January 1st +Jan 1 15, January 1st and January 15th +Sun !(Dec 25), Sunday, NOT December 25 +Sat Sun Aug, Saturday and Sundays in August ``` ## Date Groups @@ -108,9 +88,9 @@ Sun !(Dec 25), Every Sunday except Dec 25. The ! does NOT expand t (Jun 25)-(Sep 1) 2025, Alternative summer vacation ``` -## Ranges (`-`) +## Ranges -You can specify ranges with a dash for days, weekdays, months, years, and date groups. +You can specify ranges between conditions of the same type with a hyphen ``` Mon-Fri, Work every weekday @@ -126,29 +106,12 @@ Fri -(Sep 12 2025), Every Friday before (and including) Sep 12 2025 Fri (Sep 12 2025)-, Every Friday after (and including) Sep 12 2025 ``` -## Logic (AND, OR, NOT) - -The date string is a list of conditions. Each condition of a different type (day, month, etc.) has to met for days the event takes place. - -If multiple conditions of the same type exist, any of them can be satisfied. - -Prepend any condition with `!` to mean NOT. - -``` -Fri Jan, Friday AND January (Every Fri in Jan) -1 15, 1st OR 15th -Fri !13, Friday, NOT the 13th -Sun !(Dec 25), Sunday, NOT December 25 -2025 Aug 14, 2025 AND August AND the 14th -Sat Sun Aug, Saturday OR Sundays, in August -``` - -## First/last week(s) of Month (`W`, `L`) +## First/last week(s) of Month -xW is the xth set of 7 days of a month\ -xL is the xth-from-last set of 7 days of a month +[N]W is the Nth set of 7 days of a month\ +[N]L is the Nth-from-last set of 7 days of a month -This is mostly useful for certain holidays and is analogous to the 'a' and 'b' parameters in When. +This is mostly useful for certain holidays ``` May 2W Sun, Mother's Day (Second Sunday of May) @@ -165,58 +128,49 @@ Fri 06:00, With no am/pm, 24h time is assumed Fri 12:00am, Midnight Fri 12pm, Noon -# You can include ranges if you'd like +# You can use ranges too Fri 05:00-06:00, Breakfast Fri 12pm-1pm, Lunch ``` -## Modified Julian Day (`J%x+y`) - Repeat every N days +## Adding details to events + +Any line starting with a `+` is attached to the nearest above event. This can be used for details about an event if you don't want to put everything on one line. + +``` +2025 Jan 5 16:00, Doctor's Appointment ++ 123 Gentoo Road, San Francisco, CA 12345 ++ Dr. Elias Berkins, +1 (555)-123-1234 +``` + +## Advanced Recurrence (Modified Julian Day `J%x+y`) Soon supports using a Modified Julian Day as `J`. `J` is the number of full days since midnight November 17, 1858. This can be used along with the modulo operator `%` to create complex recurring events. -This condition returns **true** when the result is 0. This is the opposite of how When works! You are almost always hunting zeros with this function so it makes no sense to invert it every time. +This condition returns **true** when the result is 0 (This is the opposite of how When works). ``` J%3, Every third day J%14-5, Every other Saturday J%14+2, Every other Saturday (on the other weeks) Sat J%2, Every other Saturday expressed in a different way - -# You can use it for recurring reminders too -Jul 10-19 2025 J%3-2, This event repeats July 10, 13, 16, 19 ``` -Julian date modulus is definitely weird, but it's a concise way to express multiple uncommon recurring patterns without increasing program complexity and syntax vocabulary for features I virtually never use. Plus it's an homage to [When](https://www.lightandmatter.com/when/when.html), and I love When. +Julian date modulus is weird, but it's a concise way to express multiple uncommon recurring patterns without increasing program complexity and syntax vocabulary for features I virtually never use. Plus it's an homage to [When](https://www.lightandmatter.com/when/when.html). -### Footnote for astronomers and time nerds +#### Footnote for astronomers and time nerds The actual MJD is based on UTC, so Soon technically uses a *rounded*, modified Julian Day because it counts days since 1858-11-17 in your local time zone. This doesn't matter in practice. It's just a number that goes up by 1 every day. Soon's MJD is off by 1 from When. When starts counting from JD 1 while Soon more correctly starts counting from JD 0. -# Archive File - -You can archive events in interactive mode with `soon i`. This lets you archive an event like "Pay rent" early so you know it's done. - -- For recurring events with no end date, only the individual instance is archived. -- For events with one date, the event is removed from your calendar file. -- For events with an end date, it will only be removed from your calendar file if all occurences are archived. - -`showPastArchivedEvents` and `showFutureArchivedEvents` determine if archived events are hidden from your agenda entirely or show up as (Archived). - -## Keep events on calendar until manually archived +## Todo List -In soon.config, set `alwaysShowUnarchivedEvents=true` and old events will stick on your calendar until archived (regardless of the `past` setting). This means you will have to manually acknowledge every event. - -Soon checks for events starting from `startDate` so you don't get recurring events showing up from the 1970s. Basically, everything before this date is considered archived. - -# Todo List - -Lines in .soon files that start with `-` will show up on the todo list. +Lines in .soon files that start with `-` will show up on the todo list. -Lines starting with `+` are attached to the todo above it, similar to events. +Start a line with `+` to attach it to the above todo. -If you add a line with `+ Due:` followed by a date, it will show up separately from your events in a list of upcoming deadlines. +Attach a line with `+ Due: DATE` and it will show up in a list of upcoming deadlines. ``` - Wash car @@ -228,34 +182,44 @@ If you add a line with `+ Due:` followed by a date, it will show up separately f + Due: Aug 7 2025 ``` -If you delete an event in interactive mode, it will be deleted from the .soon file. +You can delete finished todos from `then i` or just from your text editor. -# Why would I use this? +# Archive File + +You can archive events in interactive mode with `soon i`. This lets you archive an event like "Pay rent" early so you know it's done. -Soon was created as alternative to [When](https://www.lightandmatter.com/when/when.html) with nicer syntax and a few extra todo/scheduling features. It's for a small niche of people who mainly edit their schedule directly in a text file rather than a TUI. This group almost exclusively uses [Remind](https://dianne.skoll.ca/projects/remind/) or [Org Mode](https://orgmode.org). +- For recurring events with no end date, only the individual instance is archived. +- For events with one date, the event is removed from your calendar file. +- For events with an end date, it will only be removed from your calendar file if all occurences are archived. + +`showPastArchivedEvents` and `showFutureArchivedEvents` determine if archived events are hidden from your agenda entirely or show up as (Archived). + +#### Keep events on calendar until manually archived + +In soon.config, set `alwaysShowUnarchivedEvents=true` and old events will stick on your calendar until archived (regardless of the `past` setting). This means you will have to manually acknowledge every event. + +Soon checks for events starting from `startDate` so you don't get recurring events showing up from the 1970s. Basically, everything before this date is considered archived. + +# Why would I use this? -Soon has a few benefits over similar text file calendars: +Soon is a [When](https://www.lightandmatter.com/when/when.html) alternative with nicer syntax and scheduling features for a small niche of people who mainly edit their schedule directly in a text file. This group largely uses [Remind](https://dianne.skoll.ca/projects/remind/) or [Org Mode](https://orgmode.org). Soon has a few benefits over similar text file calendars: -1. Soon has the most concise syntax. It minimizes special characters and simplifies ranges. +1. Soon has the most concise syntax. **Soon**: `Jul 1-7 2025, Vacation!`\ **When**: `m=Jul & d>=1 & d<=7 & y=2025, Vacation!`\ **Remind**: `REM Jul 1 2025 THROUGH Jul 7 2025 MSG Vacation!` -2. Soon can archive instances of events early - -Take the event "Pay quarterly bill", scheduled every 3 months. If I do that a week early, I can archive it so it's gone from my calendar. This won't affect other upcoming instances. - -3. Soon can keep events around until you archive them +2. Soon can archive the next instance of "Pay quarterly bill" after its paid early to hide it from your agenda without affecting later instances. -By setting `alwaysShowUnarchivedEvents=true`, Soon will keep every event on your calendar until you archive it. This mimics the behavior I used to have of keeping calendar reminders in my email inbox until they were done. +3. Optionally keep all events on the agenda until manually archived. This mimics the behavior of keeping overdue calendar reminders in your email inbox. -4. Soon can show a todo list and upcoming deadlines. +4. Zero nonsense todos with upcoming deadlines. # Alternatives - [When](https://www.lightandmatter.com/when/when.html) - The simplest text file calendar that's flexible enough for real world use. -- [Remind](https://dianne.skoll.ca/projects/remind/) - The most powerful, programmable calendar program ever made +- [Remind](https://dianne.skoll.ca/projects/remind/) - The most powerful, programmable calendar program ever made. - [Better overview here.](https://blog.thechases.com/posts/remind/) - [Org Mode](https://orgmode.org) - Expansive text file based productivity system but an endless time sink for tinkerers. @@ -265,10 +229,11 @@ You might also be interested in these which are text based but have somewhat dif - Todos - Todos with deadlines -- TUI - Calendar output -- Color +- Open editor - Julian modulus calculator (`soon -j Jun 5 2025` > Outputs J and a table of common mod offsets) +- Color +- TUI - CalDAV/.ics export? - Numerous CLI programs store calendars with .ics files directly, so it doesn't make much sense to use Soon if you need to sync to a "main" calendar. - Import? |