man page

5 files changed, 179 insertions, 6 deletions

diff --git a/.gitignore b/.gitignore
index 6745e1c..09c3515 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,4 @@ doc
 *.gem
 coverage
 test/dot_hcl
+*.1
diff --git a/Gemfile b/Gemfile
index b133fde..8de4533 100644
--- a/Gemfile
+++ b/Gemfile
@@ -1,6 +1,7 @@
 source "https://rubygems.org"
 gemspec
 gem 'pry', group:['test','development']
+gem 'ronn', group:['development']
 # XXX this is dumb but it's crazy hard to get platform specfic deps into a gemspec
 gem 'rubysl-abbrev', platform:'rbx'
 gem 'rubysl-singleton', platform:'rbx'
diff --git a/Rakefile b/Rakefile
index f6b7b7b..5d74ebf 100644
--- a/Rakefile
+++ b/Rakefile
@@ -1,9 +1,6 @@
-require 'rubygems/tasks'
-Gem::Tasks.new
-
 require 'fileutils'
 task :clean do
-  FileUtils.rm_rf %w[ pkg coverage doc ]
+  FileUtils.rm_rf %w[ pkg coverage doc man/hcl.1 ]
 end
 
 require 'rake/testtask'
@@ -13,7 +10,15 @@ Rake::TestTask.new do |t|
 end
 task :default => :test
 
+task :man do
+  system 'ronn -r man/hcl.1.ronn'
+end
+task 'build:gem' => [:man]
+
 require 'yard'
 YARD::Rake::YardocTask.new
-task :doc => :yard
+task :doc => [:yard, :man]
+
+require 'rubygems/tasks'
+Gem::Tasks.new
 
diff --git a/hcl.gemspec b/hcl.gemspec
index cf1c615..201649b 100644
--- a/hcl.gemspec
+++ b/hcl.gemspec
@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   s.description = "HCl is a command-line client for manipulating Harvest time sheets."
   s.executables = ["hcl"]
   s.files = %w[CHANGELOG LICENSE Rakefile Gemfile] + Dir['*.markdown'] +
-    Dir['bin/*'] + Dir['lib/**/*.rb'] + Dir['test/**/*.rb']
+    Dir['bin/*'] + Dir['lib/**/*.rb'] + Dir['test/**/*.rb'] + Dir['man/hcl.1']
   s.homepage = "http://zackhobson.com/hcl/"
   s.licenses = ["MIT"]
   s.summary = "Harvest timesheets from the command-line"
diff --git a/man/hcl.1.ronn b/man/hcl.1.ronn
new file mode 100644
index 0000000..52ebd9d
--- /dev/null
+++ b/man/hcl.1.ronn
@@ -0,0 +1,166 @@
+hcl(1) -- Track time with Harvest time sheets
+=============================================
+
+## SYNOPSIS
+
+    hcl [start] @<task_alias> [+<time>] [<message>]
+    hcl note <message>
+    hcl stop [<message>]
+    hcl resume [@<task_alias>]
+    hcl log @<task_alias> [+<time>] [<message>]
+    hcl show [<date>]
+    hcl tasks [<project_code>]
+    hcl alias <task_alias> <project_id> <task_id>
+    hcl aliases
+    hcl (cancel | nvm | oops)
+    hcl config
+
+## DESCRIPTION
+
+HCl is a command-line tool for interacting with Harvest time sheets using the
+Harvest time tracking API.
+
+### Available Projects and Tasks
+
+To start a new timer you need to identify the project and task.
+The tasks command displays a list of available tasks with their
+project and task IDs.
+
+    hcl tasks
+
+You can also pass a project code (this is the short optional code associated
+with each project) to list only the tasks for that project.
+
+### Starting a Timer
+
+Since it's not practical to enter two long numbers every time you want to
+identify a task, HCl supports task aliases:
+
+    hcl alias tacodev 1234 5678
+    hcl @tacodev Adding a new feature
+
+### Starting a Timer with Initial Time
+
+You can also provide an initial time when starting a new timer.
+This can be expressed in floating-point or HH:MM. The following two
+commands are equivalent:
+
+    hcl @tacodev +0:15 Doing some stuff
+    hcl +.25 @tacodev Doing some stuff
+
+### Adding Notes to a Running Task
+
+While a task is running you can append lines to the task notes:
+
+    hcl note Then I did something else
+
+**Note** that `show` only displays the last line of the timer notes.
+You can list all the notes for a running timer by issuing the note
+command without any arguments:
+
+    hcl note
+
+### Stopping a Timer
+
+The following command will stop a running timer (currently only one timer at
+a time is supported). You can provide a message when stopping a timer as
+well:
+
+    hcl stop All done doing things
+
+### Resuming a Timer
+
+You can resume a stopped timer. Specify a task to resume the last timer
+for that task:
+
+    hcl resume
+    hcl resume @xdev
+
+### Canceling a Timer
+
+If you accidentally started a timer that you didn't mean to, you can cancel
+it:
+
+    hcl cancel
+
+This will delete the running timer, or the last-updated timer if one isn't
+running. You can also use `nvm` or `oops` instead of `cancel`.
+
+### Logging without Starting a Timer
+
+You can log time and notes without leaving a timer running. It takes
+the same arguments as start:
+
+    hcl log @xdev +1 Worked for an hour.
+
+The above starts and immediately stops a one-hour timer with the given note.
+
+## ADVANCED USAGE
+
+### Bash Auto-completion of Task Aliases
+
+You can enable auto-completion of task aliases by adding this to your shell
+configuration:
+
+    eval `hcl completion`
+
+### Configuration Profiles
+
+You can modify your credentials with the `--reauth` option, and review them
+with `hcl config`. If you'd rather store multiple configurations at
+once, specify an alternate configuration directory in the environment as
+`HCL_DIR`. This can be used to interact with multiple harvest accounts at
+once.
+
+Here is a shell alias `myhcl` with a separate configuration from the
+main `hcl` command, and another command to configure alias completion:
+
+    alias myhcl="env HCL_DIR=~/.myhcl hcl"
+    eval `myhcl completion myhcl`
+
+Adding something like the above to your bashrc will enable a new command,
+`myhcl`. When using `myhcl` you can use different credentials and aliases,
+while `hcl` will continue to function with your original configuration.
+
+### Interactive Console
+
+An interactive Ruby console is provided to allow you to use the fairly
+powerful Harvest API client built into HCl, since not all of its
+features are exposed via the command line. The current {HCl::App}
+instance is available as `hcl`.
+
+It's also possible to issue HCl commands directly (except `alias`, see
+below), or to query specific JSON end points and have the results
+pretty-printed:
+
+    hcl console
+    hcl> show "yesterday"
+    # => prints yesterday's timesheet, note the quotes!
+    hcl> hcl.http.get('daily')
+    # => displays a pretty-printed version of the JSON output
+
+Note that the HCl internals may change without notice.
+Also, commands (like `alias`) that are also reserved words in Ruby
+can't be issued directly (use `send :alias` instead).
+
+### Date Formats
+
+Dates can be expressed in a variety of ways. See the [Chronic documentation][cd]
+for more information about available date input formats. The following
+commands show the time sheet for the specified day:
+
+    hcl show yesterday
+    hcl show last friday
+    hcl show 2 days ago
+    hcl show 1 week ago
+
+[cd]: http://chronic.rubyforge.org/
+
+## AUTHOR
+
+HCl was designed and implemented by Zack Hobson.
+
+* Non-SSL support by Michael Bleigh.
+* Resume command by Brian Cooke.
+* UI improvements by Chris Scharf.
+