mutt-ical

This is a collection of scripts that make it easier to work with iCalendar files in mutt. (Note that this is for calendar information in the iCalendar file format. It has nothing to do with the OSX calendar program.)

The scripts include the following programs, which are described in more detail further down:

• viewical – Prints out a text summary of the events in an iCalendar file.
• ical-reply – Intended to facilitate responses to iCalendar email invitations. Not yet functional.

Installation

The recommended installation method is to use pipx to install the module:

pipx install mutt-ical

You can also use pip, which will mingle the module into the current Python environment:

pip install mutt-ical

Or you can download the .whl file from the latest release.

Finally, there's the manual option:

1. Install Poetry
2. Clone this repository (git clone https://github.com/asciipip/mutt-ical.git)
3. In the cloned repo, run poetry build
4. Install the .whl file from the dist directory

viewical

viewical takes an iCalendar file on standard input and prints out a more human-friendly rendering of the data in the file. It's intended to be used as a display filter in mutt.

Usage

This is easiest if you maintain a mutt-specific mailcap, e.g. having this in your ~/.muttrc:

set mailcap_path="${HOME}/.mutt/mailcap:/etc/mailcap"

In your mailcap, add entries for the appropriate MIME types:

text/calendar; viewical; copiousoutput
application/ics; viewical; copiousoutput

In your .muttrc, tell mutt to automatically display calendar data:

auto_view text/calendar
auto_view application/ics

Finally, you need to add (or modify) the alternative_order setting in your .muttrc to prefer iCalendar attachments over their HTML or text alternatives, for messages sent with such alternatives:

alternative_order text/calendar text/plain text/html

Output

Most of the script's output should be self-explanatory. Most fields are optional, so it'll only print information (from event end times to locations to event descriptions) if they're present in the original data.

One thing to note is the encoding of attendees (or, in iCalendar terminology, "participants"). They're presented in a list with a checkbox of sorts next to them, something like this:

[ ] Barb Example <[email protected]>

People will get different boxes depending on the role defined for them in the iCalendar data. The boxes are as follows:

• { } - Event chairperson.
• [ ] - Attendee, participation required. (Most programs use this as the default role.)
• < > - Attendee, participation optional.
• ( ) - Non-participant. (The author of these scripts has never seen this in actual use.)
• _ _ - No role defined in the data.
• ? ? - Unknown role.

The script places text in the box to indicate the status of the person. The statuses are as follows:

• blank - Unknown. (Officially, this is "needs action", i.e. "waiting for a response".)
• Y - Attending.
• - - Not attending.
• ~ - Maybe attending.
• ? - Status not recognized by script.

(In the event that the iCalendar data does not define a status, the box will be empty, not just blank. This is "status unknown to organizer": [ ]. This is "status not present in data": []. That's not a huge difference, but every file the script's author has observed has had some status defined for every person attached to an event.)

Example

Here's an event with a chairperson, two required attendees, and two non-required attendees. The chairperson and one required attendee have responded that they will attend. The other required attendee has not yet responded. One of the non-required attendees will not attend and the other is tentative.

Organizer: Admin Aid <[email protected]>
Event:     Example Event
Date:      Thursday, August 4, 2016
Starts:    9:00 am
Ends:      10:00 am
Location:  Meeting Room 7
Attendees: {Y} Important Executive <[email protected]>
           [Y] Relevant Manager <[email protected]>
           [ ] Relevant Subordinate <[email protected]>
           <-> Affiliated Manager <[email protected]>
           <~> Irrelevant Manager <[email protected]>

ical-reply

ical-reply is intended to facilitate responses to iCalendar emails. It's not ready for use yet.

Release Process

• Update changelog
• Update version number in pyproject.toml
• Commit changes
• Add release version tag
• poetry build
• poetry publish
• Make a release on GitHub, attaching the wheel and tar files in dist