MHC – Message Harmonized Calendaring system.

DESCRIPTION

MHC is a simple and powerful calendar tool, which consists of a CLI tool written in Ruby (mhc) and a nifty Emacs frontend UI (mhc.el).

You can get the latest version from:

• https://github.com/yoshinari-nomura/mhc
• http://www.quickhack.net/mhc

MHC has following features:

• Easy import from existing Emacs buffers
  • MHC will guess the title, date, time and description from the content of buffer.
• Simple plain-text data format
  • MHC stores articles in similar format to MH (email); you can manipulate them by many other text-manipulation tools, editors, UNIX command-line tools or your own scripts.
• Flexible output format
  • Currently plain-text, iCalendar, S-formula (mhc.el, calfw), org-table, howm, JSON: (full-calendar) are supported.
• Selective export to Google Calendar with flexible filters and modifiers.
  • MHC can export custom-filtered calendars to Google Calendar via CalDaV. Check mhc-config.yml for details.

SYSTEM REQUIREMENTS

• Ruby 2.1 or newer
• Emacs 24 or newer

INSTALL AND SETUP

Ruby CLI (mhc)

mhc CLI command can be installed from rubygems.org.

$ gem install mhc

Or, if you want to install mhc in a sandbox (recommended), Bunlder would help you:

$ gem install bundler
$ mkdir /path/to/install/mhc
$ cd /path/to/install/mhc
$ bundle init
$ echo 'gem "mhc"' >> Gemfile
$ bundle install --path=vendor/bundle --binstubs=bin
$ export PATH=/path/to/install/mhc/bin:$PATH

Then, initialize config file and spool directory:

$ mhc init ~/mhc

# Read comments in config.yml carefully
$ vi ~/.config/mhc/config.yml

# Add Japanese Holidays if needed.
$ cp samples/japanese-holidays.mhcc ~/mhc/presets/

Check if mhc is working correctly:

$ mhc scan thismonth

Emacs UI (mhc.el)

You have to install Ruby CLI before install mhc.el

MHC is now available on MELPA. If you set up packaging system correctly, You can install mhc with package.el (M-x package-install mhc). Check MELPA usage for details.

And then, M-x mhc will show up the monthly calendar.

USAGE

Ruby CLI (mhc)

mhc help

Emacs UI (mhc.el)

Keybind

1. Jump and Show

   n/p, h/j/k/l would work as expected.

   Key	Function
   <	Show previous month
   P	Show previous year
   >	Show next month
   N	Show next year
   g	Go to specific month
   v	Toggle message window
   RET/SPC/./DEL	Show/scroll message buffer
   /	Search by keyword

2. Manipulate articles

   Key	Function
   E	Create a new article draft interactively
   M	Open pointed article to edit
   D	Delete pointed article
   C	Copy article temporally as a reusable template
   R	Copy article like C using completing-read
   Y	Same as E but use the template stored by C

3. Draft Buffer

   Key	Function
   C-cC-c	Finish editing and register to DB
   C-cC-q	Discard editing buffer w/o touching DB

Article format

Example

MHC stores every article in the form of RFC822-like format. Once you open a new article draft in Emacs by typing E, You may feel the draft is very similar to email’s one. This is an example of MHC article:

X-SC-Subject: Home party
X-SC-Location: my second house
X-SC-Day: 20150715
X-SC-Time: 18:00-21:00
X-SC-Category: Private Party
X-SC-Cond:
X-SC-Recurrence-Tag: HomeParty
X-SC-Duration:
X-SC-Record-Id: C34D89F5-27FA-4243-AC6C-168D8D243D9A
X-SC-Sequence: 0

This is a sample schedule article about a home party scheduled on
20150715 18:00-21:00. MHC schedule articles are similar to RFC822
style message like this.  In the header part, you can place any extra
headers you want.  if you import an article from existing email, you
may want to insert the original email headers such as Subject,
From, Date.

Time related headers

MHC has four types of headers to specify time/date-range or recurring conditions:

• X-SC-Day
• X-SC-Time
• X-SC-Cond
• X-SC-Duration

X-SC-Day

X-SC-Day: specifies an enumeration of occurrence dates separated by white space:

X-SC-Day: 20150704          ... all-day event
X-SC-Day: 20150704-20150705 ... two-days long single event
X-SC-Day: 20150704 20150705 ... two all-day events

If X-SC-Time: is specified with X-SC-Day:, X-SC-Time: acts on all enumerated dates in X-SC-Day:. So, you cannot set multiple-days value (20150704-20150705) with X-SC-Time:. You can also put ! prefix to specify the exception days (See below about X-SC-Cond:)

X-SC-Time

X-SC-Time: specifies a time range in a day or a point of time like:

X-SC-Time: 10:00-12:00
X-SC-Time: 10:00

You can leave it blank for all-day events.

With the combination of X-SC-Day:, you can specify some particular time-range of a day. Currently, you cannot specify a time-range across the multiple days.

X-SC-Cond

X-SC-Cond: defines a rule of recurrence; weekly, monthly or yearly. You can place these keywords in X-SC-Cond: separating by white spaces:

Keyword	Purpose
01/02/.../31	Day of month
1st/2nd/3rd/4th/5th/Last	Week order in a month
Sun/Mon/.../Sat	Day of week
Jan/Feb/.../Dec	Name of month

Example:

X-SC-Cond: Fri         ... Every Friday
X-SC-Cond: Tue Fri     ... Every Tueday and Friday
X-SC-Cond: 31 Aug      ... August 31st every year
X-SC-Cond: 1           ... First day on every month
X-SC-Cond: 1st 3rd Fri ... First and Third Friday every month
X-SC-Cond: Fri 13      ... 13th on every month or every Friday (not Friday 13th)

Sometimes you may want to set a particular date as exception. In such case, you can exclude a date by placing !YYYYMMDD in X-SC-Day:. For example:

X-SC-Day: !20150715 20150716
X-SC-Cond: Wed
X-SC-Duration: 20150701-20150731

This article occurs every Wednesday in July 2015 with the exception
of 2015-07-15 (Wed) and inclusion of 2015-07-16 (Thu).

X-SC-Duration

X-SC-Duration: acts on X-SC-Cond: to bounds the recurrence rule in an inclusive manner. Note that, X-SC-Duration: itself does not define any concrete occurrences and does not act on X-SC-Day:.

Example:

X-SC-Day: !20150715 20150801
X-SC-Cond: Wed
X-SC-Duration: 20150701-20150731

Every Wednesday in July 2015 with the exception
of 2015-07-15 (Wed) and inclusion of 2015-08-01 (Sat).

Headers for Grouping

X-SC-Category

X-SC-Category: is a space separated list of category It is useful for selective display both in CLI:

mhc scan today --category=Private

and Emacs UI:

M-x mhc-set-default-category
Default Category: Private && !Party

Also useful sync with Google Calendar. See mhc-config.yml for details.

X-SC-Recurrence-Tag

X-SC-Recurrence-Tag: is a tag for bundling multiple event articles as one recurring group.

MHC allows flexible description of repeating events using X-SC-Cond:, X-SC-Duration:, or X-SC-Day:. However, we know this is not sufficient.

For example, in my experience, some monthly meetings do not have distinct recurring patterns such like “Third Wednesday of each month.” Instead, the next date is fixed by coordination during the meeting.

In such cases, it is difficult to mark these events as a series of related events. That’s why we need X-SC-Recurrence-Tag:

Using X-SC-Recurrence-Tag:, MHC suggests what event should be arranged.

mhc stuck_recurrences

will tell you to make the next appointment.

For example, if you have “X-SC-Recurrence-Tag: Dentist” in your articles of past dentist events, mhc will point out that you forgot to make your next dentist appointment.

INFORMATION FOR DEVELOPERS

INSTALL for developers:

1. Install rbenv + ruby-build (see https://github.com/sstephenson/rbenv#basic-github-checkout for details)

   $ git clone https://github.com/sstephenson/rbenv.git ~/.rbenv
   $ git clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build
   # Edit your shell dot files to add some path and environment variables.
       

2. Install Latest Ruby and bundler

   # Install ruby 2.1.2
   $ rbenv install 2.1.2
   
   # Installation check
   $ rbenv global 2.1.2
   $ ruby -v # -> You will see: ruby 2.1.2...
   
   # Install bundler for your new Ruby
   $ gem install bundler
   
   # If you want to use Ruby in your sytem, say /usr/bin/ruby
   $ rbenv global system
   $ ruby -v
       

3. Clone MHC from github

   $ git clone [email protected]:yoshinari-nomura/mhc.git ~/src/mhc
       

4. Set default ruby version in MHC project

   $ cd ~/src/mhc
   $ echo '2.1.2' > .ruby-version
   $ ruby -v # -> You will see: ruby 2.1.2...
       

5. Install requied gem packages in sandbox ~/src/mhc/vendor/bundle

   $ cd ~/src/mhc
   $ bundle install --path vendor/bundle
       

6. Initialize config file and spool directory

   $ bin/mhc init ~/mhc
   
   Guessing current local timezone ...
             ok  guess timezone ... Asia/Tokyo
   Making directries under ~/mhc ...
         create  ~/mhc/draft
         create  ~/mhc/inbox
         create  ~/mhc/presets
         create  ~/mhc/spool
         create  ~/mhc/trash
         create  ~/mhc/status/cache
         create  ~/mhc/status/log
         create  ~/mhc/status/sync_channels
   Copying config file(s) into ~/.config/mhc/config.yml ...
             ok  copy ~/.config/mhc/config.yml
   Done.
   
   # Read comments in config.yml carefully
   $ vi ~/.config/mhc/config.yml
   
   # Add Japanese Holidays if needed.
   $ cp samples/japanese-holidays.mhcc ~/mhc/presets/
   
   # Add ~/src/mhc/bin directory to your $PATH for dogfooding
   $ export PATH=$HOME/src/mhc/bin:$PATH
       

7. Byte-compile Emacs client

   $ cd emacs
   $ make
       

8. Add setup in your .emacs.d/init.el

   (setq load-path
         (cons "~/src/mhc/emacs" load-path))
   (autoload 'mhc "mhc" "Message Harmonized Calendar system." t)
   (autoload 'mhc-import "mhc" "Import a schedule." t)
   
   ;; M-x mhc
       

9. Check if TODAY is good.

   $ mhc scan today
       

You may add ~/src/mhc/bin directory to your $PATH for dogfooding

DIRECTORY STRUCTURE

Configuration Directory

Default configuration directory is ~/.config/mhc. If environment variable MHC_CONFIG_HOME or XDG_CONFIG_HOME is set, it is taken as $MHC_CONFIG_HOME/mhc or $XDG_CONFIG_HOME/mhc.

Configuration directory ~/.config/mhc has these stuffs:

config.yml

Configuration file (mandatory).

plugins

Your home-made Ruby functions.

See samples for details.

Spool Directory

Location of the spool directory should be set by TOPDIR: element in config.yml.

For example, if you have TOPDIR: ~/MHC entry in your config.yml, you will have these directory structure under ~/MHC:

spool/*.mhc

MHC event database. All events are flatly located in this directory in the form of {x-sc-message-id}.mhc

draft/*.mhc

Draft files of events. Opening a file in directory by Emacs, and Typing C-cC-c will move the file into spool directory. (Not implemented yet. Should be empty for now.)

inbox/*.mhc

Mainly same as spool. You will have a chance to review these events in this directory afterwards. (Not implemented yet. Should be empty for now.)

presets/*.mhcc

Database for fixed anniversary events such as birthdays or national holidays.

trash/*.mhc

Removed events from spool directory.

status/

cache/*

Cache files for speed-up. You can remove these files without any damage to MHC Database.

log/*

log files for debug. You can remove these files without any damage to MHC DB.

sync_channels/*

Sync records of MHC DB. If you remove any files under this directory, MHC Sync will be DAMAGED.

HOW TO CONVERT FROM THE OLD MHC SPOOL

update-uuid.sh would help you.

New format is:

• X-SC-Record-Id is now in UUID style.
• Each filename is in the form of {UUID}.mhc, not [0-9]+.
• UUID in X-SC-Record-Id is same as its file’s base name.
• All articles are flatly placed in TOP/spool/ directory.

$ ./update-uuid.sh ~/Mail/schedule ~/mhc

Converting... logfile will be in /Users/nom/mhc/update-uuid.sh34485.log

For Japanese people, character-code conversion might be needed.

$ cd ~/mhc/spool
$ find . -name '*.mhc' | xargs -n 10 nkf --overwrite