#+TITLE: MHC -- Message Harmonized Calendaring system. #+AUTHOR: Yoshinari Nomura #+EMAIL: #+DATE: 2015-03-16 #+OPTIONS: H:3 num:2 toc:nil #+OPTIONS: ^:nil @:t \n:nil ::t |:t f:t TeX:t #+OPTIONS: skip:nil #+OPTIONS: author:t #+OPTIONS: email:nil #+OPTIONS: creator:nil #+OPTIONS: timestamp:nil #+OPTIONS: timestamps:nil #+OPTIONS: d:nil #+OPTIONS: tags:t #+TEXT: #+DESCRIPTION: #+KEYWORDS: #+LANGUAGE: ja #+LATEX_CLASS: jsarticle #+LATEX_CLASS_OPTIONS: [a4j]
[[file:https://badge.fury.io/rb/mhc.svg]] [[http://melpa.org/#/mhc][file:http://melpa.org/packages/mhc-badge.svg]]
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:
MHC has following features:
Easy import from existing Emacs buffers
Simple plain-text data format
Flexible output format
Selective export to Google Calendar with flexible filters and modifiers.
SYSTEM REQUIREMENTS
INSTALL AND SETUP ** Ruby CLI (mhc) mhc CLI command can be installed from rubygems.org. #+BEGIN_SRC shell-script $ gem install mhc #+END_SRC
Or, if you want to install mhc in a sandbox (recommended), Bunlder would help you: #+BEGIN_SRC shell-script $ 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 #+END_SRC
Then, initialize config file and spool directory: #+BEGIN_SRC shell-script $ mhc init ~/mhc
$ vi ~/.config/mhc/config.yml
$ cp samples/japanese-holidays.mhcc ~/mhc/presets/ #+END_SRC
Check if mhc is working correctly: #+BEGIN_SRC shell-script $ mhc scan thismonth #+END_SRC
** Emacs UI (mhc.el) You have to install Ruby CLI before install mhc.el
MHC is now available on [[http://melpa.org/][MELPA]]. If you set up packaging system correctly, You can install mhc with package.el (=M-x= =package-install= =mhc=). Check [[https://github.com/milkypostman/melpa#usage][MELPA usage]] for details.
And then, =M-x mhc= will show up the monthly calendar.
** 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: #+BEGIN_EXAMPLE 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. #+END_EXAMPLE
** Time related headers MHC has four types of headers to specify time/date-range or recurring conditions:
*** X-SC-Day =X-SC-Day:= specifies an enumeration of occurrence dates separated by white space: #+BEGIN_EXAMPLE 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 #+END_EXAMPLE
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: #+BEGIN_EXAMPLE X-SC-Time: 10:00-12:00 X-SC-Time: 10:00 #+END_EXAMPLE 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:
#+BEGIN_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)
#+END_EXAMPLE
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:
#+BEGIN_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).
#+END_EXAMPLE
*** 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:
#+BEGIN_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).
#+END_EXAMPLE
** 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 [[https://github.com/yoshinari-nomura/mhc/blob/master/samples/DOT.mhc-config.yml][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:
Install rbenv + ruby-build (see https://github.com/sstephenson/rbenv#basic-github-checkout for details) #+BEGIN_SRC shell-script $ git clone https://github.com/sstephenson/rbenv.git ~/.rbenv $ git clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build
#+END_SRC
Install Latest Ruby and bundler #+BEGIN_SRC shell-script
$ rbenv install 2.1.2
$ rbenv global 2.1.2 $ ruby -v # -> You will see: ruby 2.1.2...
$ gem install bundler
$ rbenv global system $ ruby -v #+END_SRC
Clone MHC from github #+BEGIN_SRC shell-script $ git clone git@github.com:yoshinari-nomura/mhc.git ~/src/mhc #+END_SRC
Set default ruby version in MHC project #+BEGIN_SRC shell-script $ cd ~/src/mhc $ echo '2.1.2' > .ruby-version $ ruby -v # -> You will see: ruby 2.1.2... #+END_SRC
Install requied gem packages in sandbox ~/src/mhc/vendor/bundle #+BEGIN_SRC shell-script $ cd ~/src/mhc $ bundle install --path vendor/bundle #+END_SRC
Initialize config file and spool directory #+BEGIN_SRC shell-script $ 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.
$ vi ~/.config/mhc/config.yml
$ cp samples/japanese-holidays.mhcc ~/mhc/presets/
$ export PATH=$HOME/src/mhc/bin:$PATH #+END_SRC
Byte-compile Emacs client #+BEGIN_SRC shell-script $ cd emacs $ make #+END_SRC
Add setup in your =.emacs.d/init.el= #+BEGIN_SRC emacs-lisp (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 #+END_SRC
Check if TODAY is good. #+BEGIN_SRC shell-script $ mhc scan today #+END_SRC
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 [[file:samples][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 [[https://gist.github.com/yoshinari-nomura/bb9a197e0e01ad81c883][update-uuid.sh]] would help you.
New format is:
#+BEGIN_SRC shell-script $ ./update-uuid.sh ~/Mail/schedule ~/mhc
Converting... logfile will be in /Users/nom/mhc/update-uuid.sh34485.log #+END_SRC
For Japanese people, character-code conversion might be needed. #+BEGIN_SRC shell-script $ cd ~/mhc/spool $ find . -name '*.mhc' | xargs -n 10 nkf --overwrite #+END_SRC
FAQs
Unknown package
We found that mhc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.