paradeiser 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4dcbd4bf94f9cbba76054b78656e283c3b626d32
-  data.tar.gz: 4368ba13bf80540e2a58bc76e49bb2347a1275e3
+  metadata.gz: bee8d6c4f066abbede76f32b8bd4bb6eaffadce7
+  data.tar.gz: 220abdcc0e1bcdf6ef2d2819c5c903508f42da8a
 SHA512:
-  metadata.gz: 91a9cd45c540b4be0ee843f525329dd7f53287cfb0e8b746df60dae4ad1968a04077e7bae9a1249024d8eeab7b8cb718d25b29860e0efc29663810454d49c9fc
-  data.tar.gz: f72225528fedafccf789eb37a23daf9294803d0aa623e06da9a040844c049fd171a7efaf092382551833bfccbca79ae09450822a41f19469854bb9774b16a614
+  metadata.gz: 82e436e805e7159115ef9b814140f7e62ba1363d9e4af9fc6b18b9cf0bdbbb1efb355fe74f3febe19a61780989ff70df917b8dfbbf7f1229d7f1c79684bc9854
+  data.tar.gz: 40435ad4870ec1e3479bd9f82ef6168cd515cd89f6b0f437646092e1ab8d6d5e34301f93b5a8460f8286847365f7554c43bfeb3a1ba654b119568a8d50a03016

data/Gemfile

@@ -4,7 +4,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
-  gem 'rake', '~> 10.0.0'
+  gem 'rake'
   gem 'minitest', '~> 5.0.0'
-  gem 'fakefs', '~> 0.4.0', :require => "fakefs/safe"
+  gem 'fakefs', :require => "fakefs/safe"
 end

data/README.md

@@ -3,13 +3,14 @@
 [![Gem Version](https://badge.fury.io/rb/paradeiser.png)](http://badge.fury.io/rb/paradeiser)
 [![Build Status](https://secure.travis-ci.org/nerab/paradeiser.png?branch=master)](http://travis-ci.org/nerab/paradeiser)
 
-  _This project is developed with the [readme-driven development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) method. This file describes the functionality that is actually implemented, whereas the [VISION](VISION.md) describes the vision where the tool should go._
+  _This project is developed with the [readme-driven development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) method. This file describes the functionality that is actually implemented, whereas the [VISION](VISION.md) reflects the vision where the tool should go._
 
 Paradeiser is a command-line tool for the [Pomodoro Technique](http://www.pomodorotechnique.com/). It keeps track of the current pomodoro and assists the user in managing active and past pomodori:
 
-* Records finished pomodori
+* Records finished and cancelled pomodori as well as internal and external interruptions and other events
 * Keeps track of the timer for the active pomodoro and the break
-* Provides out-of-the-box reports
+* Provides out-of-the-box reports that show details about finished and cancelled pomodori
+* Shows information about breaks and interruptions
 
 Paradeiser itself is not concerned with the actual management of tasks. There are plenty of tools for that; e.g. [TaskWarrior](http://taskwarrior.org/).
 
@@ -19,7 +20,7 @@ Paradeiser itself is not concerned with the actual management of tasks. There ar
 
   There must never be more than one pomodoro [xor](http://en.wikipedia.org/wiki/Xor) break at any given time.
 
-This is scoped to a single user account (not just the `$POM_DIR` directory, but also the `at` queue).
+This is scoped to a single user account (not just the `$PAR_DIR` directory, but also the `at` queue).
 
 ## Installation
 
@@ -29,31 +30,54 @@ This is scoped to a single user account (not just the `$POM_DIR` directory, but
 
 ### Start a new pomodoro
 
-      $ pom start
+      $ par pomodoro start
 
-Because of Rule #1, calling start while a pomodoro is active will print an error message.
+If a break is still active, it will be stopped before the new pomodoro is started. Because of Rule #1, calling start while a pomodoro is active will print an error message.
 
 ### Finish the pomodoro
 
-      $ pom finish
+      $ par pomodoro finish
 
-If a pomodoro is active, it will be marked as successful after stopping it, regardless of whether the 25 minutes are over or not.
+If a pomodoro is active, it will be marked as successful after stopping it, regardless of whether the 25 minutes are over or not. Remaining arguments, if present, will be added to the pomodoro as annotation.
 
 If there is no active pomodoro, an error message will be printed.
 
+### Record an interruption of the current pomodoro
+
+      $ par interrupt
+      $ par interrupt --external
+
+Remaining arguments, if present, will be added to the interrupt as annotation. If no pomodoro is active, the command will throw an error.
+
+### Start a break
+
+      $ par break [start]
+
+If there is an active pomodoro, an error message will be printed. The `start` command is optional and may be omitted (it's only there for symmetry with `par break finish`, see the section about `at`).
+
+By default the break will be five minutes long.
+
+While there is a command to stop a break (see the section about `at`), it isn't really necessary to call it from a user's perspective. Either a new pomodoro is started, which will implicitely stop the break, or the break ends naturally because it is over. We do not track break time.
+
+### Cancel the pomodoro
+
+      $ par pomodoro cancel Just couldn't concentrate anymore.
+
+It will be marked as unsuccessful (remember, a pomodoro is indivisible). If no pomodoro is active, the command will throw an error. If a break is active, the command will do nothing except printing a warning. Remaining arguments, if present, will be added to the pomodoro as annotation.
+
 ### Initialize Paradeiser
 
 * Initialize the default directory that is used to store the Paradeiser configuration and data:
 
-          $ pom init
+          $ par init
 
-  Creates the `$POM_DIR` directory and the sample hooks in `$POM_DIR/hooks`. The data store will not be created on `pom init`, but when the first write operation happens (e.g. `pom start`, but not `pom report`).
+  Creates the `$PAR_DIR` directory and the sample hooks in `$PAR_DIR/hooks`. The data store will not be created on `par init`, but when the first write operation happens (e.g. `par pomodoro start`, but not `par report`).
 
 * Initialize an abritrary directory
 
-          $ pom init /tmp
+          $ par init /tmp
 
-  This command initializes `/tmp` as `$POM_DIR`.
+  This command initializes `/tmp` as `$PAR_DIR`.
 
 ## Timer with `at`
 
@@ -64,13 +88,17 @@ A central aspect of the Pomodoro Technique is the timer function:
 
 The `at` command is used for this. We just tell it to call
 
-      pom finish
+      par pomodoro finish
+
+when the pomodoro is over. A similar command exists as
 
-when the pomodoro is over.
+      par break finish
+
+which is called by `at` when the break is over.
 
 When a pomodoro is started, Paradeiser enqueues itself to `at` like this:
 
-      echo pom finish | at now + 25 minutes
+      echo par pomodoro finish | at now + 25 minutes
 
 When `at` calls Paradeiser with this command, the pomodoro / break will be over and Paradeiser can do all the internal processing related to stopping the pomodoro / break (incl. calling the appropriate hooks, see below).
 
@@ -78,60 +106,91 @@ Paradeiser uses a dedicated at queue named 'p' to organize its jobs and to preve
 
 ## Status
 
-Paradeiser can print the current status to STDOUT with the `pom status` command. The current state is provided as process exit status (which is also useful when the output is suppressed).
+Paradeiser can print the current status to STDOUT with the `par status` command. The current state is provided as process exit status (which is also useful when the output is suppressed).
 
 * Given an active pomodoro:
 
-          $ pom status
+          $ par status
           Pomodoro #2 is active (started 11:03, 14 minutes remaining).
 
-          $ pom status > /dev/null
+          $ par status > /dev/null
           $ echo $?
           0
 
 * Given no active pomodoro and the last one (not earlier as today) was finished:
 
-          $ pom status
+          $ par status
           No active pomodoro. Last one was finished at 16:58.
 
-          $ pom status > /dev/null
+          $ par status > /dev/null
           $ echo $?
           1
 
+* Given no active pomodoro and the last one (not earlier as today) was cancelled:
+
+          $ par status
+          No pomodoro active. Last pomodoro was cancelled at 17:07.
+
+          $ par status > /dev/null
+          $ echo $?
+          2
+
+* Given a break (implies no active pomodoro):
+
+          $ par status
+          Taking a 5 minute break until 2013-07-16 17.07 (4 minutes remaining).
+
+          $ par status > /dev/null
+          $ echo $?
+          3
+
 ## Reports
 
-      $ pom report
-      <list of pomodori>
+      $ par report
+
+## Output Policy
+Paradeiser follows the [Rule of Silence](http://www.faqs.org/docs/artu/ch01s06.html#id2878450). If all goes well, a command will not print any output to `STDOUT` unless `--verbose` is given. `status`, `report` and `timesheet` are exempted from this rule, as their primary purpose is to print to STDOUT.
 
 ## Hooks
-Instead of handling tasks itself, Paradeiser integrates with external tools via hooks. Every event will attempt to find and execute an appropriate script in `$POM_DIR/hooks/`. Sufficient information will be made available via environment variables.
+Instead of handling tasks itself, Paradeiser integrates with external tools via hooks. Every event will attempt to find and execute an appropriate script in `$PAR_DIR/hooks/`. Sufficient information will be made available via environment variables.
 
-`before-` hooks will be called before the action is executed internally. If a `before-`hook exits non-zero, paradeiser will abort the action and exit non-zero itself; indicating in a message to STDERR which hook caused the abort.
+`before-` hooks will be called before the action is executed internally. If a `before-`hook exits non-zero, paradeiser will abort the action and exit non-zero itself; indicating in a message to STDERR which hook caused the abort. In this case it will not process `after-` hooks.
 
 `after-` hooks will be called after the action was executed internally. The exit status of a `post`-hook will be passed through paradeiser, but it will not affect the execution of the action anymore.
 
 ### Available Hooks
 
-* `before-start` is called after the `start` command was received, but before internal processing for the `start` action begins
-* `after-start` is called after all interal processing for the `start` action ended
-* `before-finish` is called after the timer of the current pomodoro fired (the pomodoro is over), but before internal processing for the `finish` action begins
-* `after-finish` is called after all interal processing for the `finish` action ended
+* `before-start-pomodoro` is called before the processing of the start action begins.
+* `after-start-pomodoro` is called after the processing of the start action ended.
+* `before-finish-pomodoro` is called after the timer of the current pomodoro fired (the pomodoro is over), but before the processing of the `finish` action begins.
+* `after-finish-pomodoro` is called after the processing of the `finish` action ended.
+
+* `before-start-break` is called before the processing of the break start action begins.
+* `after-start-break` is called after the processing of the break start action ended.
+* `before-finish-break` is called after the timer of the current break fired (the break is over), but before the processing of the break finish action begins.
+* `after-finish-break` is called after the processing of the break finish action ended.
+* `before-interrupt-pomodoro` is called when the `interrupt` command was received, but before the action processing begins.
+* `after-interrupt-pomodoro` is called after the processing of the `interrupt` action ended.
+* `before-cancel-pomodoro` is called when the `cancel` command was received, but before the processing of the cancel action begins.
+* `after-cancel-pomodoro` is called after the processing of the `cancel` action ended.
 
 Examples for the use of hooks are:
 
-* Displaying a desktop notification on `after-finish`
+* Displaying a desktop notification on `after-finish-pomodoro`
 * tmux status bar integration like [pomo](https://github.com/visionmedia/pomo) by writing the status to `~/.pomo_stat` from the `after-` hooks.
 * Displaying a desktop notification
 
-`$POM_TITLE` is one of the environment variables set by Paradeiser that provides the context for hooks. See below for the full list of available environment variables.
+`$PAR_TITLE` is one of the environment variables set by Paradeiser that provides the context for hooks. See below for the full list of available environment variables.
 
 ## Environment Variables
 
 Variable | Used in | Description
 --- | --- | ---
-`$POM_DIR` | Everywhere | Directory where the data store and the hooks are stored. Defaults to `~/.paradeiser/`.
-`$POM_ID` | Hooks | Identifier of the pomodoro
-`$POM_STARTED_AT` | Hooks | Timestamp of when the pomodoro was started
+`$PAR_DIR` | Everywhere | Directory where the data store and the hooks are stored. Defaults to `~/.paradeiser/`.
+`$PAR_POMODORO_ID` | Hooks | Identifier of the pomodoro
+`$PAR_POMODORO_STARTED_AT` | Hooks | Timestamp of when the pomodoro was started
+`$PAR_BREAK_ID` | Hooks | Identifier of the break
+`$PAR_BREAK_STARTED_AT` | Hooks | Timestamp of when the break was started
 
 ## Similar Projects
 
@@ -147,14 +206,16 @@ They have a lot of what I wanted, but pomo focuses very much on the tasks themse
 ### State Machine
 Paradeiser uses a [state machine](https://github.com/pluginaweek/state_machine) to model a pomodoro. Internal event handlers do the actual work; among them is the task of calling the external hooks.
 
-![State Transition Diagram](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Pomodoro_status.svg)
+![State Transition Diagram for Pomodoro](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Pomodoro_status.svg)
+![State Transition Diagram for Break](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Break_status.svg)
 
 The graph was created using the rake task that comes with `state_machine`:
 
     rake state_machine:draw CLASS=Paradeiser::Pomodoro TARGET=doc FORMAT=svg HUMAN_NAMES=true ORIENTATION=landscape
+    rake state_machine:draw CLASS=Paradeiser::Break    TARGET=doc FORMAT=svg HUMAN_NAMES=true ORIENTATION=landscape
 
 ## API
-The actual storage backend is *not a public API* and may change at any given time.
+The actual storage backend is *not a public API* and may change at any given time. External tools should use the Ruby API instead, or rely on the JSON export / import.
 
 ## Sync
 In todays world of distributed devices, synching data is a problem almost every app needs to solve. Paradeiser is no exception - it is very easy to come up with use cases that involve many computers. Maybe the user has different devices (mobile and desktop), maybe the user works in different environments, and wants to record all pomodori into a single system.

data/TODO.md

@@ -1,23 +1,22 @@
 # Paradeiser Backlog
 
-* Implement break
+* Add `par report` with a single (global) view that implements the report format described in the vision document (but isn't scoped yet)
 
-  Cancel all enqueued commands on `pom break`, just like with `pom start`. Otherwise commands already enqueued to `at` would accidentially change a newer thing while thinking of operating on the older thing.
+* Implement `par pomodoro annotate` and annotations for most commands. Alias it it `par annotate`.
 
-  This is safe (and required) because of Rule #1.
+* Improve status messages with relative times and dates (`distance_of_time_in_words_to_now`)
+  => action_view/helpers/date_helper
 
-* Implement interrupts
+* Simplify the status view. Separate views by class (break vs. pomodoro).
 
-* Implement `pom annotate` and annotations for most commands
+* Refactor the hooks tests: extract the common code
 
-* Improve status messages with relative times and dates (`distance_of_time_in_words_to_now`)
+* Whenever par runs, it should garbage-collect pomodori or breaks (finish them and adjust their finish time) that weren't finished after they were over (e.g. because at isn't there or the hooks did not fire)
 
-* POM_ID is not available to `*-start` hooks because the pomodoro wasn't saved yet. We could either assign it before saving it or allow saving idle pomodori.
+* Extend commander to allow abbreviated commands with Ruby's `Abbrev` module
 
 * A text-based repo format would be much more UNIX-like. Think about a JSON repo. Loading it could share a lot of code with import (which we will need anyway). And we cannot trust a JSON repo any more than an import file.
 
-* Make `start` the default subcommand for `pom break`, so that `pom break` is the same as `pom break start`.
-
 * Have the router catch warnings (those errors that extend Warning) and print the message to STDERR, but do not exit. The actual exit code is still determined by the controller.
 
 * Add more tests for the scheduler (error cases like no access, or job not added due to other issues)
@@ -28,9 +27,9 @@
   - The view only shows the id for any given day in most reports. That means that a day (current by default, others in queries or import) is the scope of a pomodoro id.
   - We don't have to globally identify pomodori with uuids because of rule #1
 
-  This also makes `pom import` simple - only if there is nothing on record for the time between the start and end times of the imported thing, it is accepted into our system.
+  This also makes `par import` simple - only if there is nothing on record for the time between the start and end times of the imported thing, it is accepted into our system.
 
-  Deleting or overwriting existing pomodori is not supported. Manual editing, if ever needed, can be done with exporting, deleting the db file, fixing up the exported file, and importing it into a fresh $POM_DIR.
+  Deleting or overwriting existing pomodori is not supported. Manual editing, if ever needed, can be done with exporting, deleting the db file, fixing up the exported file, and importing it into a fresh $PAR_DIR.
 
   Active pomodori or breaks are not exported or imported.
 
@@ -39,19 +38,19 @@
   - Errors red, warnings yellow, otherwise white
   - Turn off when running w/o tty and when --no-color is given
 
-* Print only the id of the pom that was just created / modified / queried when not running in a tty
+* Print only the id of the par that was just created / modified / queried when not running in a tty
   - test with `if $stdin.tty?`
   - If that approach works well, suggest it for TaskWarrior too (for bulk actions, e.g. in scripts)
 
 * Implement documentation Approach
-  - `pom help` is what the user will use to get information.
-  - Not sure how to allow the user to look at features that are not related to a command. Either extend `pom help` to accept arbitrary keywords, or look into 'gem man`.
+  - `par help` is what the user will use to get information.
+  - Not sure how to allow the user to look at features that are not related to a command. Either extend `par help` to accept arbitrary keywords, or look into 'gem man`.
 
   Development Tasks
 
   - Describe each feature / command in one md file (alternatively, store at GitHub issues as feature, would allow discussion).
   - When a feature is done, move it to a doc file (not the readme; it's getting too big) or a wiki page.
-  - `pom help <command>` consumes the feature files.
+  - `par help <command>` consumes the feature files.
   - Feature files could be exported onto a the github wiki or static pages about Paradeiser.
   - As part of finishing a feature, the feature file is moved from the backlog file to in individual doc file, and the README is updated to mention that feature.
 

data/VISION.md

@@ -20,7 +20,7 @@ Paradeiser itself is not concerned with the actual management of tasks. There ar
 
   There must never be more than one pomodoro [xor](http://en.wikipedia.org/wiki/Xor) break at any given time.
 
-This is scoped to a single user account (not just the `$POM_DIR` directory, but also the `at` queue).
+This is scoped to a single user account (not just the `$PAR_DIR` directory, but also the `at` queue).
 
 ## Installation
 
@@ -30,14 +30,14 @@ This is scoped to a single user account (not just the `$POM_DIR` directory, but
 
 ### Start a new pomodoro
 
-      $ pom start
+      $ par pomodoro start
 
 If a break is still active, it will be stopped before the new pomodoro is started. Because of Rule #1, calling start while a pomodoro is active will print an error message.
 
 ### Finish the pomodoro
 
-      $ pom finish
-      $ pom finish This one went very well.
+      $ par pomodoro finish
+      $ par pomodoro finish This one went very well.
 
 If a pomodoro is active, it will be marked as successful after stopping it, regardless of whether the 25 minutes are over or not. Remaining arguments, if present, will be added to the pomodoro as annotation.
 
@@ -45,24 +45,24 @@ If there is no active pomodoro, an error message will be printed.
 
 ### Record an interruption of the current pomodoro
 
-      $ pom interrupt --external Phone call from boss
-      $ pom interrupt --internal "Couldn't stay away from Twitter"
+      $ par interrupt
+      $ par interrupt --external
 
 Remaining arguments, if present, will be added to the interrupt as annotation. If no pomodoro is active, the command will throw an error.
 
 ### Start a break
 
-      $ pom break [start] [--short | --long]
+      $ par break [start] [--short | --long]
 
-If there is an active pomodoro, an error message will be printed. The `start` command is optional and may be omitted (it's only there for symmetry with `pom break end`, see the section about `at`).
+If there is an active pomodoro, an error message will be printed. The `start` command is optional and may be omitted (it's only there for symmetry with `par break finish`, see the section about `at`).
 
-By default the break will be five minutes long. After four pomodori within a day, the break will be 30 minutes long. This can be overridden with `--short` or `--long`, with an optional argument value that determines the lenght of the break in minutes (e.g. `pom break --short=10`).
+By default the break will be five minutes long. After four pomodori within a day, the break will be 30 minutes long. This can be overridden with `--short` or `--long`, with an optional argument value that determines the lenght of the break in minutes (e.g. `par break --short=10`).
 
 While there is a command to stop a break (see the section about `at`), it isn't really necessary to call it from a user's perspective. Either a new pomodoro is started, which will implicitely stop the break, or the break ends naturally because it is over. We do not track break time.
 
 ### Annotate a pomodoro
 
-      $ pom annotate This was intense, but I am happy about the work I finished.
+      $ par pomodoro annotate This was intense, but I am happy about the work I finished.
 
 The annotation will be added to the active or, if none is active, to the most recently finished or cancelled pomodoro. If no text is given, the annotation text is read from STDIN.
 
@@ -70,15 +70,15 @@ Breaks cannot have annotations.
 
 ### Cancel the pomodoro
 
-      $ pom cancel Just couldn't concentrate anymore.
+      $ par pomodoro cancel Just couldn't concentrate anymore.
 
 It will be marked as unsuccessful (remember, a pomodoro is indivisible). If no pomodoro is active, the command will throw an error. If a break is active, the command will do nothing except printing a warning. Remaining arguments, if present, will be added to the pomodoro as annotation.
 
 ### Log a pomodoro
 
-      $ pom log
+      $ par pomodoro log
 
-Add a successfully finished pomodoro that was never recorded as being started (maybe the user forgot to call `pom start`). It will appear in the reports and will count towards efficiency calculations.
+Add a successfully finished pomodoro that was never recorded as being started (maybe the user forgot to call `par pomodoro start`). It will appear in the reports and will count towards efficiency calculations.
 
 The current time will be used for the finish timestamp, and the start time will be calculated from the finish time backwards.
 
@@ -86,72 +86,72 @@ The current time will be used for the finish timestamp, and the start time will
 
 * Initialize the default directory that is used to store the Paradeiser configuration and data:
 
-          $ pom init
+          $ par init
 
-  Creates the `$POM_DIR` directory and the sample hooks in `$POM_DIR/hooks`. The data store will not be created on `pom init`, but when the first write operation happens (e.g. `pom start`, but not `pom report`).
+  Creates the `$PAR_DIR` directory and the sample hooks in `$PAR_DIR/hooks`. The data store will not be created on `par init`, but when the first write operation happens (e.g. `par pomodoro start`, but not `par report`).
 
 * Initialize an abritrary directory
 
-          $ pom init /tmp
+          $ par init /tmp
 
-  This command initializes `/tmp` as `$POM_DIR`. It also sets the config variable `dir` in `~/.pomrc`:
+  This command initializes `/tmp` as `$PAR_DIR`. It also sets the config variable `dir` in `~/.pomrc`:
 
-          $ pom config
+          $ par config
 
-If the `at` command is not available or not enabled, `pom init` will issue a warning. The program will continue because it is still useful for recording, although it will not be able to enqueue itself in order to execute the (time-based) `before-finish` and `before-break` hooks.
+If the `at` command is not available or not enabled, `par init` will issue a warning. The program will continue because it is still useful for recording, although it will not be able to enqueue itself in order to execute the (time-based) `before-finish-pomodoro` and `before-finish-break` hooks.
 
 ### Troubleshooting
 
-`pom doctor` performs a number of checks that ensure that Paradeiser can run with best results.
+`par doctor` performs a number of checks that ensure that Paradeiser can run with best results.
 
 It checks if
 
 * `at` is there and enabled
 * ...
 
-`pom doctor` also provides a hint on how to correct that situation.
+`par doctor` also provides a hint on how to correct that situation.
 
 ### Location
 Recording the location of a pomodoro allows Paradeiser to compare the average count of successful and cancelled pomodori and the number of interruptions by location, so that a report can tell in which environment we get the most work done.
 
   * Show the current location
 
-        $ pom location
+        $ par location
         Home Office
 
-        $ pom location --verbose
+        $ par location --verbose
         Home Office (macbook@01:23:45:67:89:0A)
 
   * List all locations
 
-        $ pom locations
+        $ par locations
         Home Office
         Starbucks
 
-        $ pom locations --verbose
+        $ par locations --verbose
         Home Office (macbook@01:23:45:67:89:0A)
         Starbucks (macbook@45:01:89:0A:67:23)
 
   * Show the label of a location identifier
 
-        $ pom location macbook@01:23:45:67:89:0A
+        $ par location macbook@01:23:45:67:89:0A
          Home Office
 
   * Show the identifier of a location
 
-        $ pom location "Home Office"
+        $ par location "Home Office"
         macbook@01:23:45:67:89:0A
 
   * Label a location
 
-        $ pom location macbook@01:23:45:67:89:0A "Your Label"
+        $ par location macbook@01:23:45:67:89:0A "Your Label"
 
-Paradeiser will automatically figure out the current location from the hostname and the MAC address of the default gateway (see below for details). This can be overridden by setting `$POM_LOCATION` or with a command line option:
+Paradeiser will automatically figure out the current location from the hostname and the MAC address of the default gateway (see below for details). This can be overridden by setting `$PAR_LOCATION` or with a command line option:
 
-    $ pom location --location="On the road"
+    $ par location --location="On the road"
     On the road
 
-    $ POM_LOCATION="On the road" pom location
+    $ PAR_LOCATION="On the road" par location
     On the road
 
 Both the `--location` option and the environment variable can be passed to almost all commands.
@@ -165,17 +165,17 @@ A central aspect of the Pomodoro Technique is the timer function:
 
 The `at` command is used for this. We just tell it to call
 
-      pom finish
+      par pomodoro finish
 
 when the pomodoro is over. A similar command exists as
 
-      pom break finish
+      par break finish
 
 which is called by `at` when the break is over.
 
 When a pomodoro is started, Paradeiser enqueues itself to `at` like this:
 
-      echo pom finish | at now + 25 minutes
+      echo par pomodoro finish | at now + 25 minutes
 
 When `at` calls Paradeiser with this command, the pomodoro / break will be over and Paradeiser can do all the internal processing related to stopping the pomodoro / break (incl. calling the appropriate hooks, see below).
 
@@ -183,57 +183,57 @@ Paradeiser uses a dedicated at queue named 'p' to organize its jobs and to preve
 
 ## Status
 
-Paradeiser can print the current status to STDOUT with the `pom status` command. The current state is provided as process exit status (which is also useful when the output is suppressed).
+Paradeiser can print the current status to STDOUT with the `par status` command. The current state is provided as process exit status (which is also useful when the output is suppressed).
 
 * Given an active pomodoro:
 
-          $ pom status
+          $ par status
           Pomodoro #2 is active (started 11:03, 14 minutes remaining).
 
-          $ pom status > /dev/null
+          $ par status > /dev/null
           $ echo $?
           0
 
 * Given no active pomodoro and the last one (not earlier as today) was finished:
 
-          $ pom status
+          $ par status
           No active pomodoro. Last one was finished at 16:58.
 
-          $ pom status > /dev/null
+          $ par status > /dev/null
           $ echo $?
           1
 
 * Given no active pomodoro and the last one (not earlier as today) was cancelled:
 
-          $ pom status
+          $ par status
           No pomodoro active. Last pomodoro was cancelled at 17:07.
 
-          $ pom status > /dev/null
+          $ par status > /dev/null
           $ echo $?
           2
 
 * Given a break (implies no active pomodoro):
 
-          $ pom status
+          $ par status
           Taking a 5 minute break until 2013-07-16 17.07 (4 minutes remaining).
 
-          $ pom status > /dev/null
+          $ par status > /dev/null
           $ echo $?
           3
 
 * Short status (03:39 remaining in the active pomodoro or break):
 
-          $ pom status --short
+          $ par status --short
           03:39
 
 * Given a break and a custom status format (resembles the format switch analog to `date +%Y-%m-%dT%H:%M:%S`):
 
-          $ pom status --format %C-%M:%S
+          $ par status --format %C-%M:%S
           B03:39
 
 * Output in JSON format
 
-          $ pom status --format JSON
+          $ par status --format JSON
           {
             "status": {
               "state": "break",
@@ -246,7 +246,7 @@ Paradeiser can print the current status to STDOUT with the `pom status` command.
 
 ## Reports
 
-      $ pom report
+      $ par report
       Daily Pomodoro Report for 2013-07-16
 
       3 pomodori finished
@@ -258,11 +258,11 @@ Paradeiser can print the current status to STDOUT with the `pom status` command.
       Most efficient location: Home Office
       Least efficient location: Coffeshop
 
-By default, the command groups by `--day`. Alternative options are `--week`, `--month` or `--year`. Without a value, the argument assumes the current day / week / month / year. The first day of the period can be specified as argument, e.g. `pom report --day=2013-07-18`. The period is parsed with [Chronic](http://chronic.rubyforge.org/), which also enables symbolic values like `pom report --month="last month"`.
+By default, the command groups by `--day`. Alternative options are `--week`, `--month` or `--year`. Without a value, the argument assumes the current day / week / month / year. The first day of the period can be specified as argument, e.g. `par report --day=2013-07-18`. The period is parsed with [Chronic](http://chronic.rubyforge.org/), which also enables symbolic values like `par report --month="last month"`.
 
 The report can also be grouped by location:
 
-      $ pom report location
+      $ par report location
       Pomodoro Location Report
 
       Home Office: 38 finished, 12 cancelled, 21 interrupts
@@ -271,11 +271,11 @@ The report can also be grouped by location:
 
       The following locations do not have a label. Assign it with
 
-        $ pom location macbook@01:23:45:67:89:0A "Your Label"
+        $ par location macbook@01:23:45:67:89:0A "Your Label"
 
 Detailed report for a single location:
 
-      $ pom report location "Home Office"
+      $ par report location "Home Office"
       Pomodoro Location Report for Home Office
 
       58 pomodori finished
@@ -288,7 +288,7 @@ Detailed report for a single location:
 
 Further grouping is also possible, e.g. by year:
 
-      $ pom report location --year=2012
+      $ par report location --year=2012
       Pomodoro Location Report for 2012
 
       233 pomodori finished
@@ -305,7 +305,7 @@ The efficiency is calculated from the number of successful vs. cancelled pomodor
 
 Efficiency can be reported by day, week, month, year, or location:
 
-      $ pom report efficiency
+      $ par report efficiency
       Efficiency Report for 2013-07-16
 
       TODO
@@ -318,14 +318,14 @@ Efficiency can be reported by day, week, month, year, or location:
 
 ### Timesheet
 
-      $ pom timesheet
+      $ par timesheet
       TODO Ordered list of pomodori and breaks, each with annotations (like a time sheet)
 
 The same options as for regular reports apply. The timesheet report also details the efficiency of each location.
 
 ### Exporting a Report
 
-      $ pom report --weekly --format JSON # weekly report in JSON format
+      $ par report --weekly --format JSON # weekly report in JSON format
       {
         "TODO": "Specify"
       }
@@ -334,36 +334,41 @@ The same options as for regular reports apply. The timesheet report also details
 Paradeiser follows the [Rule of Silence](http://www.faqs.org/docs/artu/ch01s06.html#id2878450). If all goes well, a command will not print any output to `STDOUT` unless `--verbose` is given. `status`, `report` and `timesheet` are exempted from this rule, as their primary purpose is to print to STDOUT.
 
 ## Hooks
-Instead of handling tasks itself, Paradeiser integrates with external tools via hooks. Every event will attempt to find and execute an appropriate script in `$POM_DIR/hooks/`. Sufficient information will be made available via environment variables.
+Instead of handling tasks itself, Paradeiser integrates with external tools via hooks. Every event will attempt to find and execute an appropriate script in `$PAR_DIR/hooks/`. Sufficient information will be made available via environment variables.
 
-`before-` hooks will be called before the action is executed internally. If a `before-`hook exits non-zero, paradeiser will abort the action and exit non-zero itself; indicating in a message to STDERR which hook caused the abort.
+`before-` hooks will be called before the action is executed internally. If a `before-`hook exits non-zero, paradeiser will abort the action and exit non-zero itself; indicating in a message to STDERR which hook caused the abort. In this case it will not process `after-` hooks.
 
 `after-` hooks will be called after the action was executed internally. The exit status of a `post`-hook will be passed through paradeiser, but it will not affect the execution of the action anymore.
 
 ### Available Hooks
 
-* `before-start` is called after the `start` command was received, but before internal processing for the `start` action begins
-* `after-start` is called after all interal processing for the `start` action ended
-* `before-finish` is called after the timer of the current pomodoro fired (the pomodoro is over), but before internal processing for the `finish` action begins
-* `after-finish` is called after all interal processing for the `finish` action ended
-* `before-interrupt` is called after the `interrupt` command was received, but before internal action processing begins
-* `after-interrupt` is called after all interal processing for the `interrupt` action ended
-* `before-cancel` is called after the `cancel` command was received, but before internal action processing begins
-* `after-cancel` is called after all interal processing for the `cancel` action ended
-* `before-break` is called after the `break` command was received, but before internal processing for the `break` action begins
-* `after-break` is called after the timer of the current break fired (the break is over), but after internal processing for the `break` action ended
+* `before-start-pomodoro` is called before the processing of the start action begins.
+* `after-start-pomodoro` is called after the processing of the start action ended.
+* `before-finish-pomodoro` is called after the timer of the current pomodoro fired (the pomodoro is over), but before the processing of the `finish` action begins.
+* `after-finish-pomodoro` is called after the processing of the `finish` action ended.
+
+* `before-start-break` is called before the processing of the break start action begins.
+* `after-start-break` is called after the processing of the break start action ended.
+* `before-finish-break` is called after the timer of the current break fired (the break is over), but before the processing of the break finish action begins.
+* `after-finish-break` is called after the processing of the break finish action ended.
+
+* `before-interrupt-pomodoro` is called when the `interrupt` command was received, but before the action processing begins.
+* `after-interrupt-pomodoro` is called after the processing of the `interrupt` action ended.
+
+* `before-cancel-pomodoro` is called when the `cancel` command was received, but before the processing of the cancel action begins.
+* `after-cancel-pomodoro` is called after the processing of the `cancel` action ended.
 
 Examples for the use of hooks are:
 
-* Displaying a desktop notification on `after-finish`
+* Displaying a desktop notification on `after-finish-pomodoro`
 * tmux status bar integration like [pomo](https://github.com/visionmedia/pomo) by writing the status to `~/.pomo_stat` from the `after-` hooks.
 * Displaying a desktop notification
 
-`$POM_TITLE` is one of the environment variables set by Paradeiser that provides the context for hooks. See below for the full list of available environment variables.
+`$PAR_TITLE` is one of the environment variables set by Paradeiser that provides the context for hooks. See below for the full list of available environment variables.
 
 ### Edit a hook
 
-      $ pom edit after-stop
+      $ par edit after-stop
 
 Launches `$VISUAL` (or, if empty, `$EDITOR`) with the given hook.
 
@@ -371,34 +376,35 @@ Launches `$VISUAL` (or, if empty, `$EDITOR`) with the given hook.
 
 Variable | Used in | Description
 --- | --- | ---
-`$POM_DIR` | Everywhere | Directory where the data store and the hooks are stored. Defaults to `~/.paradeiser/`.
-`$POM_ID` | Hooks | Identifier of the pomodoro
-`$POM_STARTED_AT` | Hooks | Timestamp of when the pomodoro was started
-`$POM_TITLE` | Hooks | Title of the pomodoro
-`$POM_LOCATION` | Location Commands | Location of the pomodoro
+`$PAR_DIR` | Everywhere | Directory where the data store and the hooks are stored. Defaults to `~/.paradeiser/`.
+`$PAR_POMODORO_ID` | Hooks | Identifier of the pomodoro
+`$PAR_POMODORO_STARTED_AT` | Hooks | Timestamp of when the pomodoro was started
+`$PAR_BREAK_ID` | Hooks | Identifier of the break
+`$PAR_BREAK_STARTED_AT` | Hooks | Timestamp of when the break was started
+`$PAR_LOCATION` | Location Commands | Location of the pomodoro
 
 ## Configuration File
 
-The configuration is stored in a config file. It is user-editable file, but editing the configuration is also exposed with `pom config`.
+The configuration is stored in a config file. It is user-editable file, but editing the configuration is also exposed with `par config`.
 
-      $ pom config dir
+      $ par config dir
       /home/nerab/.paradeiser
 
-      # Note how setting $POM_DIR affects pom config
-      $ POM_DIR=/tmp pom config dir
+      # Note how setting $PAR_DIR affects par config
+      $ PAR_DIR=/tmp par config dir
       /tmp
 
-      $ pom config dir /var/tmp
-      $ pom config dir
+      $ par config dir /var/tmp
+      $ par config dir
       /var/tmp
 
-`pom config` shows the _active_ config when called, i.e. it takes `$POM_DIR` into account.
+`par config` shows the _active_ config when called, i.e. it takes `$PAR_DIR` into account.
 
   Available config variables:
 
   Variable | Description
   --- | ---
-  `POM_DIR` | Directory where the data store and the hooks are stored. Defaults to `~/.paradeiser/`. Overridden by `$POM_DIR`.
+  `PAR_DIR` | Directory where the data store and the hooks are stored. Defaults to `~/.paradeiser/`. Overridden by `$PAR_DIR`.
   `AT_QUEUE` | Name of the `at` queue to use. Defaults to `p`.
 
 ## Taskwarrior Integration
@@ -429,11 +435,13 @@ They have a lot of what I wanted, but pomo focuses very much on the tasks themse
 ### State Machine
 Paradeiser uses a [state machine](https://github.com/pluginaweek/state_machine) to model a pomodoro. Internal event handlers do the actual work; among them is the task of calling the external hooks.
 
-![State Transition Diagram](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Pomodoro_status.svg)
+![State Transition Diagram for Pomodoro](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Pomodoro_status.svg)
+![State Transition Diagram for Break](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Break_status.svg)
 
 The graph was created using the rake task that comes with `state_machine`:
 
     rake state_machine:draw CLASS=Paradeiser::Pomodoro TARGET=doc FORMAT=svg HUMAN_NAMES=true ORIENTATION=landscape
+    rake state_machine:draw CLASS=Paradeiser::Break    TARGET=doc FORMAT=svg HUMAN_NAMES=true ORIENTATION=landscape
 
 ### I18N
 Paradeiser uses [I18N](https://github.com/svenfuchs/i18n) to translate messages and localize time and date formats.