expand documentation

README.md

@@ -1,80 +1,122 @@
-mutt-ical.py is meant as a simple way to display and reply to ical invitations from mutt.
+This single-file Python script `mutt-ical.py` displays and replies to [Icalendar](https://tools.ietf.org/html/rfc5545) invitations (.ics files) from mutt.
+It requires Mutt, Bash and Python with the [Vobject](http://eventable.github.io/vobject/) Python package.
 
-Warning
--------
-
-This script was written during a few days in 2013 for Python 2. I currently do
-not use it myself. There might be still issues with recent versions of Python 3.
+Installing
+----------
 
-If this script does not work for you, please consider fixing it yourself. It
-is just a few lines of code after all.
+Copy the script into a folder in your `$PATH`, (or specify the `$PATH` in your `mailcap` and `muttrc` files).
+Mark it executable by `chmod +x`.
+We will assume that you copied it into `~/bin` so that its full path is `~/bin/mutt-ical.py`.
 
-Pull requests are accepted, but please do not expect me to test them, they
-will be merged after a quick and shallow review.
+Initial Setup
+-------------
 
-You have been warned.
+* To view the calendar entry in mutt by opening the calendar entry in the attachment view (usually opened by hitting `v` after having selected a mail in mutt), add to your `mailcap` file (found at '`~/.mailcap`, `/etc/mailcap` or `$mailcap_path` set in `muttrc`) the following lines:
 
-Installing
-----------
+```
+text/calendar;    ~/bin/mutt-ical.py -D %s; copiousoutput
+text/x-vcalendar; ~/bin/mutt-ical.py -D %s; copiousoutput
+application/ics;  ~/bin/mutt-ical.py -D %s; copiousoutput
+```
 
-* Copy it into somewhere in your PATH, (or you can specify the PATH in your .mailcap)
-* Edit your mailcap (~/.mailcap or /etc/mailcap) to have the following line:
+- To view the calendar entry by opening a selected a mail in mutt, add to your .muttrc the following lines:
 
 ```
-# for replying
-text/calendar; <path>mutt-ical.py -i -e "user@domain.tld" %s
-application/ics; <path>mutt-ical.py -i -e "user@domain.tld" %s
-# for auto-view
-text/calendar; <path>mutt-ical.py -D %s; copiousoutput
-application/ics; <path>mutt-ical.py -D %s; copiousoutput
+auto_view text/calendar text/x-vcalendar application/ics text/plain text/html
+alternative_order text/calendar text/x-vcalendar application/ics text/plain text/html \
 ```
-(Don't forget to add your email address)
 
-* if you want to use auto view in the pager, use something like the following in .muttrc
-   (just an example, configure text/plain and text/html at your own discretion)
+- To reply to a calendar entry by pressing `r` in the attachment view (usually opened by hitting `v` after having selected a mail in mutt), add to your .muttrc a line such as
 
 ```
-auto_view text/calendar text/plain text/html
-alternative_order text/calendar text/plain text/html
+macro attach r \
+    "<pipe-entry>iconv -c --to-code=UTF-8 > ~/.cache/mutt.ics<enter><shell-escape>~/bin/mutt-ical.py -i -e your.email@address -s 'msmtp --account=work' ~/.cache/mutt.ics<enter>" \
+    "reply to appointment request"
 ```
 
+where you need to customize the email address `your.email@address` and the send command `msmtp --account=work`.
+If `-s` is not set, the Mutt setting `$sendmail` will be used.
 
-OSX Users
----------
+- To optionally open the Icalendar in your favorite desktop application, say `Ical`, run `xdg-open ~/.cache/mutt.ics` (on Linux, respectively `open ~/.cache/mutt.ics` on Mac OS) after the `mutt-ical.py` command, for example
 
-* For added fun on OSX, you can extend it to the following, to get iCal to open it nicely too (iCal does not care for mime types it seems):
 ```
-text/calendar; mv %s %s.ics && open %s.ics && <path>mutt-ical.py -i -e "user@domain.tld" %s.ics && rm %s.ics
+macro attach r \
+    "<pipe-entry>iconv -c --to-code=UTF-8 > ~/.cache/mutt.ics<enter><shell-escape>~/bin/mutt-ical.py -i -e your.email@address -s 'msmtp --account=work' ~/.cache/mutt.ics && xdg-open ~/.cache/mutt.ics<enter>" \
+    "reply to appointment request"
 ```
-* You can force iCal to stop trying to send mail on your behalf by replacing
-the file `/Applications/iCal.app/Contents/Resources/Scripts/Mail.scpt` with your
-own ActionScript. I went with the following: `error number -128`
-Which tells it that the user cancelled the action.
 
-    * Open AppleScript Editor, paste the code from above into a new script, then save it.
-    * Move the old script `/Applications/iCal.app/Contents/Resources/Scripts/Mail.scpt`  just in case you want to re-enable the functionality.
-    * Copy your new script into place.
 
 Usage
 -----
 
-If you configure auto_view (see above), the description should be visible in
+If you configure auto_view (as above), then the description should be visible in
 the pager.
+(Otherwise view the attachements (usually by hitting 'v'), select and open the `Icalendar` entry.)
+To reply, just open the `Icalendar` file from mutt:
 
-To reply, just open the ical file from mutt:
 * View the attachements (usually 'v')
 * Select the text/calendar entry
-* Invoke the mailcap entry (usually 'm')
+* Hit 'r'
 * Choose your reply
 
-An old sendmail wrapper is also included, but since mutt's SMTP support has now improved, rather configure your SMTP settings through mutt's config. The wrapper is kept in case someone finds it useful. However, the get_mutt_command function will need the relevant code uncommented to use it.
 
-Requirements
+Documentation
+-------------
+
+The script supports the following options: `-i`, `-a`, `-d`, `-t`, `-D`, and `-s`. The `-e` option followed by an email address and the path to an `.ics` file are required.
+If the `-D` option is used, the script will display the event details and terminate without sending any replies.
+The `-i`, `-a`, `-d`, and `-t` options are mutually exclusive;
+the last one specified determines the response type sent.
+By default, the script will use Mutt's sendmail setting to send the reply, unless the `-s` option is used to override it.
+
+It accepts the following command-line arguments:
+
+-e <your.email@address>
+    Specify the email address to send the reply from. This should be the email address that received the invitation.
+
+-i
+    Interactive mode. Prompt for user input to accept, decline, or tentatively accept the invitation.
+
+-a
+    Accept the invitation automatically without prompting.
+
+-d
+    Decline the invitation automatically without prompting.
+
+-t
+    Tentatively accept the invitation automatically without prompting.
+
+-D
+    Display only. Show the event details but do not send any reply.
+
+-s <sendmail command>
+    Specify the sendmail command to use for sending the email. If not set, the default Mutt setting will be used.
+
+filename.ics
+    The .ics file to be processed. This should be the invitation file received.
+
+Usage:
+
+    mutt-ical.py [OPTIONS] -e your@email.address filename.ics
+
+Make sure to replace the placeholder `your.email@address` with your actual email address and  `filename.ics` with the path to the .ics file when running the script.
+
+
+Hints
+-----
+
+Mac OS X iCal Users can force iCal to stop trying to send mail on your behalf by replacing
+the file `/Applications/iCal.app/Contents/Resources/Scripts/Mail.scpt` with your
+own ActionScript. Martin Sander went with the following: `error number -128`
+Which tells it that the user cancelled the action.
+
+* Open AppleScript Editor, paste the code from above into a new script, then save it.
+* Move the old script `/Applications/iCal.app/Contents/Resources/Scripts/Mail.scpt`  just in case you want to re-enable the functionality.
+* Copy your new script into place.
+
+Inspiration
 ------------
 
-mutt, python, bash, vobject:
-http://vobject.skyhouseconsulting.com/ or 'easy_install vobject'
+This forks [Martin Sander's](https://github.com/marvinthepa/mutt-ical/) whose (MIT) license restrictions apply, and which was inspired by
+[accept.py](http://weirdzone.ru/~veider/accept.py) and [Rubyforge.org Samples](http://vpim.rubyforge.org/files/samples/README_mutt.html).
 
-Inspired by:
-* http://weirdzone.ru/~veider/accept.py
-* http://vpim.rubyforge.org/files/samples/README_mutt.html

mutt-ical.py

@@ -25,10 +25,9 @@
     -i interactive
     -a accept
     -d decline
-    -t tentatively accept
-    (accept is default, last one wins)
+    -t tentatively accept (accept is default, last one wins)
     -D display only
-    -S <sendmail command>
+    -s <sendmail command>
 """ % sys.argv[0]
 
 
@@ -182,7 +181,8 @@ def organizer(ical):
         if opt == '-D':
             sys.exit(0)
         if opt == '-s':
-            sendmail = lambda: arg.split()  # If -s is provided, override sendmail with a lambda that returns the command
+            # If -s is provided, override sendmail with a lambda that returns the command
+            sendmail = lambda: arg.split() 
         if opt == '-e':
             email_address = arg
         if opt == '-i':