# HG changeset patch # User Glenn Morris # Date 1057798931 0 # Node ID 91e4e5fd11de0d31f4ccada139f243d1dfcb3e26 # Parent f9ae39b1c1e68175c45e0d11327f731418c6f99e (timeclock-use-display-time, timeclock-day-over-hook) (timeclock-workday-remaining, timeclock-status-string) (timeclock-when-to-leave, timeclock-when-to-leave-string) (timeclock-log-data, timeclock-find-discrep, timeclock-day-base) (timeclock-generate-report, timeclock-visit-timelog): Doc fix. (timeclock-modeline-display): Set the variable `timeclock-modeline-display'. (timeclock-update-modeline): Doc fix. Respect value of `timeclock-relative'. diff -r f9ae39b1c1e6 -r 91e4e5fd11de lisp/calendar/timeclock.el --- a/lisp/calendar/timeclock.el Thu Jul 10 01:00:24 2003 +0000 +++ b/lisp/calendar/timeclock.el Thu Jul 10 01:02:11 2003 +0000 @@ -155,7 +155,7 @@ 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 value of `timeclock-modeline-display') for the change to +toggle the function `timeclock-modeline-display') for the change to take effect." :set (lambda (symbol value) (let ((currently-displaying @@ -204,7 +204,7 @@ (defcustom timeclock-day-over-hook nil "*A hook that is run when the workday has been completed. -This hook is only run if the current time remaining is being display +This hook is only run if the current time remaining is being displayed in the modeline. See the variable `timeclock-modeline-display'." :type 'hook :group 'timeclock) @@ -301,7 +301,7 @@ (add-hook 'display-time-hook 'timeclock-update-modeline)) (setq timeclock-update-timer (run-at-time nil 60 'timeclock-update-modeline)))) - (setq global-mode-string + (setq global-mode-string (delq 'timeclock-mode-string global-mode-string)) (remove-hook 'timeclock-event-hook 'timeclock-update-modeline) (if (boundp 'display-time-hook) @@ -311,7 +311,7 @@ (cancel-timer timeclock-update-timer) (setq timeclock-update-timer nil))) (force-mode-line-update) - on-p)) + (setq timeclock-modeline-display on-p))) ;; This has to be here so that the function definition of ;; `timeclock-modeline-display' is known to the "set" function. @@ -400,24 +400,26 @@ (if arg (run-hooks 'timeclock-done-hook)))) +;; Should today-only be removed in favour of timeclock-relative? - gm (defsubst timeclock-workday-remaining (&optional today-only) "Return the number of seconds until the workday is complete. The amount returned is relative to the value of `timeclock-workday'. If TODAY-ONLY is non-nil, the value returned will be relative only to -the time worked today, and not to past time. This argument only makes -a difference if `timeclock-relative' is non-nil." +the time worked today, and not to past time." (let ((discrep (timeclock-find-discrep))) (if discrep - (if today-only - (- (cadr discrep)) - (- (car discrep))) + (- (if today-only (cadr discrep) + (car discrep))) 0.0))) ;;;###autoload (defun timeclock-status-string (&optional show-seconds today-only) - "Report the overall timeclock status at the present moment." + "Report the overall timeclock status at the present moment. +If SHOW-SECONDS is non-nil, display second resolution. +If TODAY-ONLY is non-nil, the display will be relative only to time +worked today, ignoring the time worked on previous days." (interactive "P") - (let ((remainder (timeclock-workday-remaining)) + (let ((remainder (timeclock-workday-remaining)) ; today-only? (last-in (equal (car timeclock-last-event) "i")) status) (setq status @@ -542,11 +544,11 @@ (floor (mod seconds 65536)) (floor (* (- seconds (ffloor seconds)) 1000000)))) +;; 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. If TODAY-ONLY is non-nil, the value returned will be relative only to -the time worked today, and not to past time. This argument only makes -a difference if `timeclock-relative' is non-nil." +the time worked today, and not to past time." (timeclock-seconds-to-time (- (timeclock-time-to-seconds (current-time)) (let ((discrep (timeclock-find-discrep))) @@ -561,12 +563,10 @@ today-only) "Return a string representing at what time the workday ends today. This string is relative to the value of `timeclock-workday'. If -NO-MESSAGE is non-nil, no messages will be displayed in the -minibuffer. If SHOW-SECONDS is non-nil, the value printed/returned -will include seconds. If TODAY-ONLY is non-nil, the value returned -will be relative only to the time worked today, and not to past time. -This argument only makes a difference if `timeclock-relative' is -non-nil." +SHOW-SECONDS is non-nil, the value printed/returned will include +seconds. If TODAY-ONLY is non-nil, the value returned will be +relative only to the time worked today, and not to past time." + ;; Should today-only be removed in favour of timeclock-relative? - gm (interactive) (let* ((then (timeclock-when-to-leave today-only)) (string @@ -609,9 +609,11 @@ (mapcar 'list timeclock-reason-list))) (defun timeclock-update-modeline () - "Update the `timeclock-mode-string' displayed in the modeline." + "Update the `timeclock-mode-string' displayed in the modeline. +The value of `timeclock-relative' affects the display as described in +that variable's documentation." (interactive) - (let ((remainder (timeclock-workday-remaining)) + (let ((remainder (timeclock-workday-remaining (not timeclock-relative))) (last-in (equal (car timeclock-last-event) "i"))) (when (and (< remainder 0) (not (and timeclock-day-over @@ -827,6 +829,11 @@ (defun timeclock-log-data (&optional recent-only filename) "Return the contents of the timelog file, in a useful format. +If the optional argument RECENT-ONLY is non-nil, only show the contents +from the last point where the time debt (see below) was set. +If the optional argument FILENAME is non-nil, it is used instead of +the file specified by `timeclock-file.' + A timelog contains data in the form of a single entry per line. Each entry has the form: @@ -1021,7 +1028,9 @@ log-data))) (defun timeclock-find-discrep () - "Find overall discrepancy from `timeclock-workday' (in seconds)." + "Calculate time discrepancies, in seconds. +The result is a three element list, containing the total time +discrepancy, today's discrepancy, and the time worked today." ;; This is not implemented in terms of the functions above, because ;; it's a bit wasteful to read all of that data in, just to throw ;; away more than 90% of the information afterwards. @@ -1122,7 +1131,8 @@ (< (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." + "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." (let ((decoded (decode-time (or time (current-time))))) (setcar (nthcdr 0 decoded) 0) (setcar (nthcdr 1 decoded) 0) @@ -1142,7 +1152,9 @@ 0))) (defun timeclock-generate-report (&optional html-p) - "Generate a summary report based on the current timelog file." + "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." (interactive) (let ((log (timeclock-log-data)) (today (timeclock-day-base))) @@ -1334,7 +1346,7 @@ ;;; A helpful little function (defun timeclock-visit-timelog () - "Open up the .timelog file in another window." + "Open the file named by `timeclock-file' in another window." (interactive) (find-file-other-window timeclock-file))