chronometrist/doc/manual.org

• Chronometrist
  • Getting started
    • Installation
    • Usage
  • How-to guides
  • Explanation
    • Design goals
    • Midnight-spanning events
      • 1. (timeclock format) When the code of the first event in the day is "o", it's a midnight-spanning event.
      • 2. Split them at the file level
      • 3. Split them at the hash-table-level
      • 4. Split them at the data-consumer level (e.g. when calculating time for one day/getting events for one day)
  • Reference
    • Legend of currently-used time formats
    • chronometrist-common.el
    • chronometrist-custom.el
    • chronometrist-diary-view.el
    • chronometrist.el
    • chronometrist-events.el
    • chronometrist-migrate.el
    • chronometrist-plist-pp.el
    • chronometrist-queries.el
    • chronometrist-report-custom.el
    • chronometrist-report.el
    • chronometrist-sexp.el
    • chronometrist-statistics-custom.el
    • chronometrist-statistics.el
    • chronometrist-time.el
    • chronometrist-timer.el
    • chronometrist-goals

Chronometrist

Getting started

Installation

Usage

How-to guides

Explanation

Design goals

1. Don't make assumptions about the user's profession

   • e.g. timeclock seems to assume you're using it for a 9-to-5/contractor job

2. Incentivize use

   • Hooks allow the time tracker to automate tasks and become a useful part of your workflow

3. Make it easy to edit data using existing, familiar tools

   • We don't use an SQL database, where changing a single field is tricky [1]
   • We use a text file containing s-expressions (easy for humans to read and write)
   • We use ISO-8601 for timestamps (easy for humans to read and write) rather than UNIX epoch time
4. Reduce human errors in tracking
5. Have a useful, informative, interactive interface
6. Support mouse and keyboard use equally

[1] I still have doubts about this. Having SQL as a query language would be very useful in perusing the stored data. Maybe we should have tried to create a companion mode to edit SQL databases interactively?

Midnight-spanning events

A unique problem in working with Chronometrist, one I had never foreseen, was tasks which start on one day and end on another. These mess up data consumption (especially interval calculations and acquiring data for a specific date) in all sorts of unforeseen ways.

There are a few different approaches of dealing with them. (Currently, Chronometrist uses #3.)

1. (timeclock format) When the code of the first event in the day is "o", it's a midnight-spanning event.

• Advantage - very simple to detect
• Disadvantage - "in" and "out" events must be represented separately

2. Split them at the file level

• Advantage - operation is performed only once for each such event + simpler data-consuming code + reduced post-parsing load.

• What happens when the user changes their day-start-time? The split-up events are now split wrongly, and the second event may get split again. Possible solutions -

  1. Add function to check if, for two events A and B, the :stop of A is the same as the :start of B, and that all their other tags are identical. Then we can re-split them according to the new day-start-time.
  2. Add a :split tag to split events. It can denote that the next event was originally a part of this one.

  3. Re-check and update the file when the day-start-time changes.

     • Possible with add-variable-watcher or :custom-set in Customize (thanks bpalmer)

3. Split them at the hash-table-level

Handled by chronometrist-events-clean

• Advantage - simpler data-consuming code.

4. Split them at the data-consumer level (e.g. when calculating time for one day/getting events for one day)

• Advantage - reduced repetitive post-parsing load.

Reference

• (?) - of dubious utility, a candidate for deprecation
• DEPRECATED - deprecated, slated to be removed in the future

Legend of currently-used time formats

1.	(Emacs) decode-time	(seconds minutes hours day month year dow dst utcoff)
2.	list-timestamp	(year month day hours minutes seconds)
3.	list-date	(year month day)
4.	list-time/list-duration	(hours minutes seconds)
5.	(?) vector-date	[year month day]
6.	(?) vector-time/vector-duration	[hours minutes seconds]
7.	(Emacs) encode-time AKA UNIX epoch	(sec-high sec-low microsec picosec)
8.	seconds	seconds as an integer
9.	minutes	minutes as an integer
10.	iso-timestamp	"YYYY-MM-DDTHH:MM:SSZ"
11.	iso-date	"YYYY-MM-DD"
12.	(DEPRECATED) timeclock-timestamp	"year/month/day hours:minutes:seconds"
13.	(DEPRECATED) timeclock-date	"year/month/day"

chronometrist-common.el

1. Variable - chronometrist-empty-time-string
2. Variable - chronometrist-date-re
3. Variable - chronometrist-time-re-ui
4. Variable - chronometrist-task-list
5. Internal Variable - chronometrist–fs-watch

6. Function - chronometrist-buffer-exists? (buffer-name)

   • String -> List?

7. Function - chronometrist-buffer-visible? (buffer-or-buffer-name)

   • Buffer | String -> Boolean

8. Function - chronometrist-format-time (duration &optional blank)

   • vector-duration | list-duration -> "hⓂ️s"
9. Command - chronometrist-open-file (&optional button)
10. Function - chronometrist-common-create-chronometrist-file ()
11. Function - chronometrist-common-file-empty-p (file)
12. Function - chronometrist-common-clear-buffer (buffer)
13. Function - chronometrist-format-keybinds (command map &optional firstonly)

14. Function - chronometrist-events->time-list (events)

    • (event …) -> ((encode-time encode-time) …)

15. Function - chronometrist-time-list->sum-of-intervals (time-value-lists)

    • ((encode-time encode-time) …) -> encode-time
16. Function - chronometrist-delete-list (&optional arg)
17. Function - chronometrist-previous-week-start (date-string)
18. Function - chronometrist-current-task ()

chronometrist-custom.el

1. Custom variable - chronometrist-file
2. Custom variable - chronometrist-buffer-name
3. Custom variable - chronometrist-hide-cursor
4. Custom variable - chronometrist-update-interval
5. Custom variable - chronometrist-activity-indicator
6. Custom variable - chronometrist-day-start-time

chronometrist-diary-view.el

1. Variable - chronometrist-diary-buffer-name
2. Internal Variable - chronometrist-diary–current-date
3. Function - chronometrist-intervals-on (date)
4. Function - chronometrist-diary-tasks-reasons-on (date)
5. Function - chronometrist-diary-refresh (&optional ignore-auto noconfirm date)
6. Major Mode - chronometrist-diary-view-mode
7. Command - chronometrist-diary-view (&optional date)

chronometrist.el

1. Internal Variable - chronometrist–task-history
2. Internal Variable - chronometrist–point
3. Variable - chronometrist-mode-map

4. Function - chronometrist-task-active? (task)

   • String -> Boolean
5. Function - chronometrist-activity-indicator ()
6. Function - chronometrist-entries ()
7. Function - chronometrist-task-at-point ()
8. Function - chronometrist-goto-last-task ()
9. Function - chronometrist-print-keybind (command &optional description firstonly)
10. Function - chronometrist-print-non-tabular ()
11. Function - chronometrist-goto-nth-task (n)
12. Function - chronometrist-refresh (&optional ignore-auto noconfirm)
13. Function - chronometrist-refresh-file (fs-event)
14. Command - chronometrist-query-stop ()
15. Variable - chronometrist-before-in-functions
16. Variable - chronometrist-after-in-functions
17. Variable - chronometrist-before-out-functions
18. Variable - chronometrist-after-out-functions
19. Function - chronometrist-run-functions-and-clock-in (task)
20. Function - chronometrist-run-functions-and-clock-out (task)
21. Variable - chronometrist-mode-map
22. Major Mode - chronometrist-mode
23. Function - chronometrist-toggle-task-button (button)
24. Function - chronometrist-add-new-task-button (button)
25. Command - chronometrist-toggle-task (&optional prefix inhibit-hooks)
26. Command - chronometrist-toggle-task-no-hooks (&optional prefix)
27. Command - chronometrist-add-new-task ()
28. Command - chronometrist (&optional arg)

chronometrist-events.el

1. Variable - chronometrist-events
2. Function - chronometrist-list-midnight-spanning-events ()
3. Function - chronometrist-day-start (timestamp)
4. Function - chronometrist-file-clean ()
5. Function - chronometrist-events-maybe-split (event)
6. Function - chronometrist-events-populate ()
7. Function - chronometrist-tasks-from-table ()
8. Function - chronometrist-events-subset (start-date end-date)
9. Function - chronometrist-events-query-spec-match-p (plist specifiers)

chronometrist-migrate.el

1. Variable - chronometrist-migrate-table
2. Function - chronometrist-migrate-populate (in-file)
3. Function - chronometrist-migrate-timelog-file->sexp-file (&optional in-file out-file)
4. Function - chronometrist-migrate-check ()

chronometrist-plist-pp.el

1. Variable - chronometrist-plist-pp-keyword-re
2. Variable - chronometrist-plist-pp-whitespace-re
3. Function - chronometrist-plist-pp-longest-keyword-length ()
4. Function - chronometrist-plist-pp-buffer-keyword-helper ()
5. Function - chronometrist-plist-pp-buffer ()
6. Function - chronometrist-plist-pp-to-string (object)
7. Function - chronometrist-plist-pp (object &optional stream)

chronometrist-queries.el

1. Function - chronometrist-task-time-one-day (task &optional date-string)

   • String &optional iso-date -> seconds

2. Function - chronometrist-active-time-one-day (&optional date-string)

   • &optional iso-date -> vector-duration
3. Function - chronometrist-statistics-count-active-days (task &optional table)
4. Function - chronometrist-task-events-in-day (task date-string)

chronometrist-report-custom.el

1. Custom variable - chronometrist-report-buffer-name
2. Custom variable - chronometrist-report-week-start-day
3. Custom variable - chronometrist-report-weekday-number-alist

chronometrist-report.el

1. Internal Variable - chronometrist-report–ui-date
2. Internal Variable - chronometrist-report–ui-week-dates
3. Internal Variable - chronometrist-report–point
4. Function - chronometrist-report-date ()
5. Function - chronometrist-report-date->dates-in-week (first-date-in-week)
6. Function - chronometrist-report-date->week-dates ()
7. Function - chronometrist-report-entries ()
8. Function - chronometrist-report-format-date (format-string time-date)
9. Function - chronometrist-report-print-keybind (command &optional description firstonly)
10. Function - chronometrist-report-print-non-tabular ()
11. Function - chronometrist-report-refresh (&optional ignore-auto noconfirm)
12. Function - chronometrist-report-refresh-file (fs-event)
13. Variable - chronometrist-report-mode-map
14. Major Mode - chronometrist-report-mode
15. Function - chronometrist-report (&optional keep-date)
16. Function - chronometrist-report-previous-week (arg)
17. Function - chronometrist-report-next-week (arg)

chronometrist-sexp.el

1. Internal Variable - chronometrist–tag-suggestions
2. Internal Variable - chronometrist–value-suggestions
3. Function - chronometrist-plist-remove (plist &rest keys)
4. Function - chronometrist-maybe-string-to-symbol (list)
5. Function - chronometrist-maybe-symbol-to-string (list)
6. Command - chronometrist-reindent-buffer ()
7. Function - chronometrist-last-expr ()
8. Function - chronometrist-append-to-last-expr (tags plist)
9. Variable - chronometrist-tags-history
10. Function - chronometrist-tags-history-populate ()
11. Function - chronometrist-tags-history-combination-strings (task)
12. Function - chronometrist-tags-history-individual-strings (task)
13. Function - chronometrist-tags-prompt (task &optional initial-input)
14. Function - chronometrist-tags-add (&rest args)
15. Custom Variable - chronometrist-kv-buffer-name
16. Variable - chronometrist-key-history
17. Variable - chronometrist-value-history
18. Function - chronometrist-ht-history-prep (table)
19. Function - chronometrist-key-history-populate ()
20. Function - chronometrist-value-history-populate ()
21. Command - chronometrist-kv-accept ()
22. Command - chronometrist-kv-reject ()
23. Variable - chronometrist-kv-read-mode-map
24. Major Mode - chronometrist-kv-read-mode
25. Function - chronometrist-kv-completion-quit-key ()
26. Function - chronometrist-string-has-whitespace-p (string)
27. Function - chronometrist-key-prompt (used-keys)
28. Function - chronometrist-value-prompt (key)
29. Function - chronometrist-value-insert (value)
30. Function - chronometrist-kv-add (&rest args)
31. Command - chronometrist-in (task &optional prefix)
32. Command - chronometrist-out (&optional prefix)

chronometrist-statistics-custom.el

1. Custom variable - chronometrist-statistics-buffer-name

chronometrist-statistics.el

1. Internal Variable - chronometrist-statistics–ui-state
2. Internal Variable - chronometrist-statistics–point
3. Variable - chronometrist-statistics-mode-map

4. Function - chronometrist-statistics-count-average-time-spent (task &optional table)

   • string &optional hash-table -> seconds
5. Function - chronometrist-statistics-entries-internal (table)
6. Function - chronometrist-statistics-entries ()
7. Function - chronometrist-statistics-print-keybind (command &optional description firstonly)
8. Function - chronometrist-statistics-format-date (date)
9. Function - chronometrist-statistics-print-non-tabular ()
10. Function - chronometrist-statistics-refresh (&optional ignore-auto noconfirm)
11. Major Mode - chronometrist-statistics-mode
12. Command - chronometrist-statistics (&optional preserve-state)
13. Command - chronometrist-statistics-previous-range (arg)
14. Command - chronometrist-statistics-next-range (arg)

chronometrist-time.el

1. Constant - chronometrist-seconds-in-day
2. Function - chronometrist-date (&optional time)
3. Function - chronometrist-day-of-week->number (day-of-week)
4. Function - chronometrist-number->day-of-week (number)
5. Function - chronometrist-format-time-iso8601 (&optional unix-time)

6. Function - chronometrist-time-interval-span-midnight? (t1 t2)

   • list-timestamp list-timestamp -> Boolean
7. Function - chronometrist-midnight-spanning-p (start-time stop-time)

8. Function - chronometrist-time->seconds (time)

   • vector-duration -> seconds

9. Function - chronometrist-seconds-to-hms (seconds)

   • seconds -> vector-duration

10. Function - chronometrist-time-add (a b)

    • vector-duration vector-duration -> vector-duration

11. Function - chronometrist-iso-date->timestamp (date)

    • iso-date -> iso-timestamp
12. Function - chronometrist-date->time (date)
13. Function - chronometrist-date-less-p (date1 date2)
14. Function - chronometrist-time-less-or-equal-p (t1 t2)
15. Function - chronometrist-calendrical->date (date)

16. Function - chronometrist-interval (event)

    • event -> encode-time

chronometrist-timer.el

1. Internal Variable - chronometrist–timer-object
2. Function - chronometrist-timer ()
3. Command - chronometrist-stop-timer ()
4. Command - chronometrist-maybe-start-timer (&optional interactive-test)
5. Command - chronometrist-force-restart-timer ()
6. Command - chronometrist-change-update-interval (arg)

chronometrist-goals

1. Custom Variable - chronometrist-goals-list nil
2. Function - chronometrist-run-at-time (time repeat function &rest args)

3. Function - chronometrist-task-minutes-one-day (task)

   • string -> minutes
4. Function - chronometrist-minutes->alert-string (minutes)
5. Function - chronometrist-approach-alert (task goal spent)
6. Function - chronometrist-complete-alert (task goal spent)
7. Function - chronometrist-exceed-alert (task goal spent)
8. Function - chronometrist-no-goal-alert (task goal spent)
9. Custom Variable - chronometrist-goals-alert-functions

10. Function - chronometrist-get-goal (task &optional targets-list)

    • String &optional List -> minutes
11. Internal Variable - chronometrist–timers-list
12. Function - chronometrist-minutes-string (minutes)
13. Function - chronometrist-goals-run-alert-timers (task)
14. Function - chronometrist-goals-stop-alert-timers (&optional _task)
15. Function - chronometrist-goals-on-file-change ()