;;; timeclock.el --- mode for keeping track of how much you work
-;; Copyright (C) 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
+;; Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
+;; Free Software Foundation, Inc.
;; Author: John Wiegley <johnw@gnu.org>
;; Created: 25 Mar 1999
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
-;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-;; Boston, MA 02111-1307, USA.
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
;;; Commentary:
;; Use `timeclock-in' when you start on a project, and `timeclock-out'
;; when you're done. Once you've collected some data, you can use
;; `timeclock-workday-remaining' to see how much time is left to be
-;; worked today (assuming a typical average of 8 hours a day), and
-;; `timeclock-when-to-leave' which will calculate when you're free.
+;; worked today (where `timeclock-workday' specifies the length of the
+;; working day), and `timeclock-when-to-leave' to calculate when you're free.
;; You'll probably want to bind the timeclock commands to some handy
-;; keystrokes. At the moment, C-x t is unused in Emacs 20:
+;; keystrokes. At the moment, C-x t is unused:
;;
;; (require 'timeclock)
;;
;; `timeclock-modeline-display' again.
;; You may also want Emacs to ask you before exiting, if you are
-;; current working on a project. This can be done either by setting
+;; currently working on a project. This can be done either by setting
;; `timeclock-ask-before-exiting' to t using M-x customize (this is
;; the default), or by adding the following to your .emacs file:
;;
;;; Code:
(defgroup timeclock nil
- "Keeping track time of the time that gets spent."
+ "Keeping track of the time that gets spent."
:group 'data)
;;; User Variables:
:group 'timeclock)
(defcustom timeclock-relative t
- "*When reporting time, make it relative to `timeclock-workday'?
+ "*Whether to maken reported time relative to `timeclock-workday'.
For example, if the length of a normal workday is eight hours, and you
work four hours on Monday, then the amount of time \"remaining\" on
Tuesday is twelve hours -- relative to an averaged work period of
eight hours -- or eight hours, non-relative. So relative time takes
-into account any discrepancy of time under-worked or overworked on
-previous days."
+into account any discrepancy of time under-worked or over-worked on
+previous days. This only affects the timeclock modeline display."
:type 'boolean
:group 'timeclock)
(defcustom timeclock-get-project-function 'timeclock-ask-for-project
"*The function used to determine the name of the current project.
When clocking in, and no project is specified, this function will be
-called to determine what the current project to be worked on is.
+called to determine what is the current project to be worked on.
If this variable is nil, no questions will be asked."
:type 'function
:group 'timeclock)
(defcustom timeclock-get-reason-function 'timeclock-ask-for-reason
"*A function used to determine the reason for clocking out.
When clocking out, and no reason is specified, this function will be
-called to determine what the reason is.
+called to determine what is the reason.
If this variable is nil, no questions will be asked."
:type 'function
:group 'timeclock)
(defcustom timeclock-get-workday-function nil
"*A function used to determine the length of today's workday.
The first time that a user clocks in each day, this function will be
-called to determine what the length of the current workday is. If
+called to determine what is the length of the current workday. If
the return value is nil, or equal to `timeclock-workday', nothing special
will be done. If it is a quantity different from `timeclock-workday',
however, a record will be output to the timelog file to note the fact that
-that day has a different length from the norm."
+that day has a length that is different from the norm."
:type '(choice (const nil) function)
:group 'timeclock)
(defcustom timeclock-ask-before-exiting t
- "*If non-nil, ask if the user wants to clock out before exiting Emacs."
+ "*If non-nil, ask if the user wants to clock out before exiting Emacs.
+This variable only has effect if set with \\[customize]."
:set (lambda (symbol value)
(if value
(add-hook 'kill-emacs-query-functions 'timeclock-query-out)
(defcustom timeclock-use-display-time t
"*If non-nil, use `display-time-hook' for doing modeline updates.
-The advantage to this is that it means one less timer has to be set
-running amok in Emacs' process space. The disadvantage is that it
-requires you to have `display-time' running. If you don't want to use
+The advantage of this is that one less timer has to be set running
+amok in Emacs' process space. The disadvantage is that it requires
+you to have `display-time' running. If you don't want to use
`display-time', but still want the modeline to show how much time is
-left, set this variable to nil. You will need to restart Emacs (or
-toggle the function `timeclock-modeline-display') for the change to
-take effect."
+left, set this variable to nil. Changing the value of this variable
+while timeclock information is being displayed in the modeline has no
+effect. You should call the function `timeclock-modeline-display' with
+a positive argument to force an update."
:set (lambda (symbol value)
(let ((currently-displaying
(and (boundp 'timeclock-modeline-display)
Normally, timeclock assumes that you intend to work for
`timeclock-workday' seconds every day. Any days in which you work
more or less than this amount is considered either a positive or
-negative discrepancy. If you work in such a manner that the
+a negative discrepancy. If you work in such a manner that the
discrepancy is always brought back to zero, then you will by
definition have worked an average amount equal to `timeclock-workday'
each day.")
This value is not accurate enough to be useful by itself. Rather,
call `timeclock-workday-elapsed', to determine how much time has been
worked so far today. Also, if `timeclock-relative' is nil, this value
-will be the same as `timeclock-discrepancy'.")
+will be the same as `timeclock-discrepancy'.") ; ? gm
(defvar timeclock-last-period nil
"Integer representing the number of seconds in the last period.
-Note that you shouldn't access this value, but should use the function
-`timeclock-last-period' instead.")
+Note that you shouldn't access this value, but instead should use the
+function `timeclock-last-period'.")
(defvar timeclock-mode-string nil
"The timeclock string (optionally) displayed in the modeline.
(progn
;; Update immediately so there is a visible change
;; on calling this function.
- (if display-time-mode (timeclock-update-modeline))
+ (if display-time-mode (timeclock-update-modeline)
+ (message "Activate `display-time-mode' to see \
+timeclock information"))
(add-hook 'display-time-hook 'timeclock-update-modeline))
(setq timeclock-update-timer
(run-at-time nil 60 'timeclock-update-modeline))))
_seconds_ worked today*. This feature only has effect the first time
this function is called within a day.
-PROJECT as the project being clocked into. If PROJECT is nil, and
+PROJECT is the project being clocked into. If PROJECT is nil, and
FIND-PROJECT is non-nil -- or the user calls `timeclock-in'
interactively -- call the function `timeclock-get-project-function' to
discover the name of the project."
"remaining" "over")
(timeclock-when-to-leave-string show-seconds today-only)))
(if (interactive-p)
- (message status)
+ (message "%s" status)
status)))
;;;###autoload
(defun timeclock-change (&optional arg project)
- "Change to working on a different project, by clocking in then out.
-With a prefix ARG, consider the previous project as having been
-finished at the time of changeover. PROJECT is the name of the last
-project you were working on."
+ "Change to working on a different project.
+This clocks out of the current project, then clocks in on a new one.
+With a prefix ARG, consider the previous project as finished at the
+time of changeover. PROJECT is the name of the last project you were
+working on."
(interactive "P")
(timeclock-out arg)
(timeclock-in nil project (interactive-p)))
;;;###autoload
(defun timeclock-query-out ()
- "Ask the user before clocking out.
+ "Ask the user whether to clock out.
This is a useful function for adding to `kill-emacs-query-functions'."
(and (equal (car timeclock-last-event) "i")
(y-or-n-p "You're currently clocking time, clock out? ")
(timeclock-workday-remaining today-only)
show-seconds t)))
(if (interactive-p)
- (message string)
+ (message "%s" string)
string)))
(defsubst timeclock-workday-elapsed ()
(let ((string (timeclock-seconds-to-string (timeclock-workday-elapsed)
show-seconds)))
(if (interactive-p)
- (message string)
+ (message "%s" string)
string)))
(defsubst timeclock-time-to-seconds (time)
;; Should today-only be removed in favour of timeclock-relative? - gm
(defsubst timeclock-when-to-leave (&optional today-only)
- "Return a time value representing at when the workday ends today.
+ "Return a time value representing the end of today's workday.
If TODAY-ONLY is non-nil, the value returned will be relative only to
the time worked today, and not to past time."
(timeclock-seconds-to-time
;;;###autoload
(defun timeclock-when-to-leave-string (&optional show-seconds
today-only)
- "Return a string representing at what time the workday ends today.
+ "Return a string representing the end of today's workday.
This string is relative to the value of `timeclock-workday'. If
SHOW-SECONDS is non-nil, the value printed/returned will include
seconds. If TODAY-ONLY is non-nil, the value returned will be
(format-time-string "%-I:%M:%S %p" then)
(format-time-string "%-I:%M %p" then))))
(if (interactive-p)
- (message string)
+ (message "%s" string)
string)))
;;; Internal Functions:
(defun timeclock-ask-for-project ()
"Ask the user for the project they are clocking into."
(timeclock-completing-read
- (format "Clock into which project (default \"%s\"): "
+ (format "Clock into which project (default %s): "
(or timeclock-last-project
(car timeclock-project-list)))
(mapcar 'list timeclock-project-list)
h Set the required working time for the given day. This must
be the first entry for that day. The COMMENT in this case is
- the number of hours that must be worked. Floating point
- amounts are allowed.
+ the number of hours in this workday. Floating point amounts
+ are allowed.
i Clock in. The COMMENT in this case should be the name of the
project worked on.
;;; A reporting function that uses timeclock-log-data
-(defun timeclock-time-less-p (t1 t2)
- "Say whether time T1 is less than time T2."
- (or (< (car t1) (car t2))
- (and (= (car t1) (car t2))
- (< (nth 1 t1) (nth 1 t2)))))
-
(defun timeclock-day-base (&optional time)
"Given a time within a day, return 0:0:0 within that day.
If optional argument TIME is non-nil, use that instead of the current time."
(apply 'encode-time decoded)))
(defun timeclock-geometric-mean (l)
- "Compute the geometric mean of the list L."
+ "Compute the geometric mean of the values in the list L."
(let ((total 0)
(count 0))
(while l
(defun timeclock-generate-report (&optional html-p)
"Generate a summary report based on the current timelog file.
By default, the report is in plain text, but if the optional argument
-HTML-P is non-nil html markup is added."
+HTML-P is non-nil, HTML markup is added."
(interactive)
(let ((log (timeclock-log-data))
(today (timeclock-day-base)))
(* 2 7 24 60 60))))
two-week-len today-len)
(while proj-data
- (if (not (timeclock-time-less-p
+ (if (not (time-less-p
(timeclock-entry-begin (car proj-data)) today))
(setq today-len (timeclock-entry-list-length proj-data)
proj-data nil)
(if (and (null two-week-len)
- (not (timeclock-time-less-p
+ (not (time-less-p
(timeclock-entry-begin (car proj-data))
two-weeks-ago)))
(setq two-week-len (timeclock-entry-list-length proj-data)))
(while day-list
(let ((i 0) (l 5))
(while (< i l)
- (unless (timeclock-time-less-p
+ (unless (time-less-p
(timeclock-day-begin (car day-list))
(aref lengths i))
(let ((base (timeclock-time-to-seconds
(if (file-readable-p timeclock-file)
(timeclock-reread-log))
+;;; arch-tag: a0be3377-deb6-44ec-b9a2-a7be28436a40
;;; timeclock.el ends here