      An Emacs Interface to Logging Hours With onShore TimeSheet

------------
Quick Start:
------------

To use the Emacs interface to onShore TimeSheet, you need three files:

   timesheet.el           -- Emacs Lisp interface to recording hours
   timesheet-log-from.pl  -- Perl script, uploads recorded hours to the server
   timesheet-get-data.pl  -- Perl script, uploads recorded hours to the server

Put the scripts somewhere on your local system, and put the following
in your .emacs to tell timesheet.el where the perl scripts live:

   (setq timesheet-logger-program   "/path/to/timesheet-log-from.pl"
         timesheet-pulldata-program "/path/to/timesheet-get-data.pl")
   
Next, load the elisp file:

   (load-file "/path/to/timesheet.el")

Now you can do "M-x timesheet".

----------------------
What's the Plan, Stan?
----------------------

timesheet.el creates the directory ~/.timesheet/ for you.  In that
directory lives a file named `hours'.  Each time you do M-x timesheet,
you are adding a new entry to the hours file, an "entry" being what
you used to submit with one click at the cafe web page -- you know, 3
hours spent on job Foo or whatever.

But these hours are not yet uploaded to the server, they're just
recorded in ~/.timesheet/hours.  To actually upload, use "M-x
timesheet-log-accumulated-hours" (or just type C-c C-c when you finish
an entry).  Emacs will send the entries one by one to `log_from.pl',
which uploads them to cafe via the web interface.  This is a slow
process, so expect your Emacs to be tied up for a few minutes.

As it uploads, it will display minibuffer messages telling you whether
each entry was accepted or rejected.  Entries are given serial numbers
based on the entry date, so you can find them in the archive files
(see below).

If you're getting Perl errors from `log_from.pl', you may need to
install some Perl WWW libraries.  Talk to Lefty, Fitz, Karl, or
Irving.

---------------------------------------------------
Information is never, ever lost, so don't even ask:
---------------------------------------------------

All entries are moved out of the `hours' file after uploading, but
they are still archived in your ~/.timesheet/ directory.  The
successful entries are appended to a file with a name like:

   ~/.timesheet/logged.Jun-19-1998

Failures accumulate in

   ~/.timesheet/errors

along with the associated HTML error output from the server.  Emacs
will tell you if it encountered any errors uploading, but you should
look in that file from time to time in any case, to make sure you're
not losing hours.

---------------------------------------------------
Random stuff that wasn't appropriate anywhere else:
---------------------------------------------------

While we're at it, you may be wondering why your `hours' buffer only
seems to show one entry at a time.  This is because it uses Emacs's
"narrowing" functions to hide all previous entries.  If you want to go
back and browse them, you can un-narrow the buffer with "M-x widen".

Also, you should type the generic Emacs major-mode-help command while
in the hours buffer sometime, to see what commands are available in
Timesheet Mode.  That command is "C-h m", also known as "M-x
describe-mode".

-----------------------
How to operate offline:
-----------------------

In order to give you completion on client and job names, timesheet.el
downloads a list of clients and jobs from the server.  By default, it
will refetch these lists the first time you do "M-x timesheet" in a
given Emacs session.  But it also caches the lists in your
~/.timesheet/ directory, so you can record hours while offline.  To
tell timesheet.el to use the cache instead of refetching, just pass it
a prefix argument, i.e. "C-u M-x timesheet".

Naturally, you can't upload hours while offline.

-------------
Improvements:
-------------

I was thinking, since we use a Perl script to upload anyway, of
removing Emacs from the upload process entirely, and having people
just run a shell command to start the upload.  Thoughts?

Ability to move up and down between entries in hours file?  C-c C-p
and C-c C-n as bindings, probably.


-------------
Limitations::
-------------

SSL (https) is not supported.  Let us know if anyone is using this and
we might be persuaded to add it.

