2019-10-30 17:02:03 +00:00
* Chronometrist
** Getting started
*** Installation
*** Usage
** How-to guides
** Explanation
*** Design goals
2019-11-09 14:21:06 +00:00
1. Don't make assumptions about the user's profession (timeclock)
2019-10-30 17:02:03 +00:00
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
2019-11-09 14:21:06 +00:00
* We don't use an SQL database, where changing a single statement is tricky [1]
2019-10-30 17:02:03 +00:00
* 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
2019-11-09 14:21:06 +00:00
[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?
2019-11-09 14:22:39 +00:00
*** 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.
2019-11-11 12:10:44 +00:00
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 (i.e. rewrite ~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.
2019-11-09 14:22:39 +00:00
2019-10-30 17:02:03 +00:00
** Reference
* (?) - of dubious utility, a candidate for deprecation
* DEPRECATED - deprecated, slated to be removed in the future
*** Legend of currently-used time formats
2019-11-09 14:25:01 +00:00
| 1. | decode-time | (seconds minutes hours day month year dow dst utcoff) |
| 2. | list-timestamp | (year month day hours minutes seconds) |
| 3. | list-time/list-duration | (hours minutes seconds) |
| 4. | list-date | (year month day) |
| 5. | vector-date | [year month day] |
| 6. | vector-time/vector-duration | [hours minutes seconds] |
| 7. | encode-time (UNIX epoch) | (sec-high sec-low microsec picosec) |
| 8. | seconds | seconds as an integer |
| 9. | iso-timestamp | "YYYY-MM-DDTHH:MM:SSZ" |
| 10. | iso-date | "YYYY-MM-DD" |
| 11. | (DEPRECATED) timeclock-timestamp | "year/month/day hours:minutes:seconds" |
| 12. | (DEPRECATED) timeclock-date | "year/month/day" |
2019-10-30 17:02:03 +00:00
*** chronometrist-common.el
1. Variable - chronometrist-empty-time-string
2. Variable - chronometrist-date-re
3. Variable - chronometrist-time-re-ui
2019-11-21 07:41:48 +00:00
4. Variable - chronometrist-task-list
5. Variable - chronometrist--fs-watch
6. Function - chronometrist-buffer-exists? (buffer-name)
2019-10-30 17:02:03 +00:00
* String -> List?
2019-11-21 07:41:48 +00:00
7. Function - chronometrist-buffer-visible? (buffer-or-buffer-name)
2019-10-30 17:02:03 +00:00
* Buffer | String -> Boolean
8. Function - chronometrist-format-time (time)
* vector-duration | list-duration -> "h:m: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)
2019-11-21 07:41:48 +00:00
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-day-start-time
2019-11-21 07:50:21 +00:00
*** chronometrist-diary-view.el
1. Variable - chronometrist-diary-buffer-name
2. 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)
2019-10-30 17:02:03 +00:00
*** chronometrist.el
2019-11-21 07:41:48 +00:00
1. Variable - chronometrist--project-history
2. Variable - chronometrist--point
3. Variable - chronometrist-mode-map
4. Function - chronometrist-task-active? (task)
2019-10-30 17:02:03 +00:00
* String -> Boolean
2019-11-21 07:41:48 +00:00
5. Function - chronometrist-entries ()
6. Function - chronometrist-project-at-point ()
7. Function - chronometrist-goto-last-project ()
8. Function - chronometrist-print-keybind (command &optional description firstonly)
9. Function - chronometrist-print-non-tabular ()
10. Function - chronometrist-goto-nth-project (n)
11. Function - chronometrist-refresh (&optional ignore-auto noconfirm)
12. Function - chronometrist-refresh-file (fs-event)
13. Variable - chronometrist-before-in-functions
14. Variable - chronometrist-after-in-functions
15. Variable - chronometrist-before-out-functions
16. Variable - chronometrist-after-out-functions
17. Function - chronometrist-run-functions-and-clock-in (task)
18. Function - chronometrist-run-functions-and-clock-out (task)
16. Variable - chronometrist-mode-map
19. Major Mode - chronometrist-mode
20. Function - chronometrist-toggle-project-button (button)
21. Function - chronometrist-add-new-project-button (button)
22. Command - chronometrist-toggle-project (&optional prefix)
23. Command - chronometrist-toggle-project-no-reason (&optional prefix)
24. Command - chronometrist-add-new-project ()
25. Command - chronometrist (&optional arg)
2019-10-30 17:02:03 +00:00
*** chronometrist-events.el
1. Variable - chronometrist-events
2019-11-21 07:41:48 +00:00
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)
2019-11-21 07:50:21 +00:00
*** 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)
2019-10-30 17:02:03 +00:00
*** chronometrist-queries.el
1. Function - chronometrist-task-time-one-day (task &optional date-string)
2. Function - chronometrist-active-time-one-day (&optional date-string)
3. Function - chronometrist-statistics-count-active-days (project &optional table)
4. Function - chronometrist-task-events-in-day (task date)
*** chronometrist-report-custom.el
2019-11-21 07:41:48 +00:00
1. Custom variable - chronometrist-report-buffer-name
2. Custom variable - chronometrist-report-week-start-day
3. Custom variable - chronometrist-report-weekday-number-alist
2019-10-30 17:02:03 +00:00
*** chronometrist-report.el
1. Variable - chronometrist-report--ui-date
2. Variable - chronometrist-report--ui-week-dates
3. Variable - chronometrist-report--point
2019-11-21 07:41:48 +00:00
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)
2019-11-21 07:50:21 +00:00
*** chronometrist-sexp.el
1. Variable - chronometrist--tag-suggestions
2. 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)
27. Function - chronometrist-value-prompt (key)
28. Function - chronometrist-kv-add (&rest args)
29. Command - chronometrist-in (task &optional prefix)
30. Command - chronometrist-out (&optional prefix)
*** chronometrist-statistics-custom.el
1. Custom variable - chronometrist-statistics-buffer-name
*** chronometrist-statistics.el
1. Variable - chronometrist-statistics--ui-state
2. Variable - chronometrist-statistics--point
3. Variable - chronometrist-statistics-mode-map
4. Function - chronometrist-statistics-count-average-time-spent (project &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)
2019-11-21 07:57:22 +00:00
8. Function - chronometrist-time->seconds (time)
2019-11-21 07:50:21 +00:00
* vector-duration -> seconds
2019-11-21 07:57:22 +00:00
9. Function - chronometrist-seconds-to-hms (seconds)
* seconds -> vector-duration
10. Function - chronometrist-time-add (a b)
2019-11-21 07:50:21 +00:00
* time-vector time-vector -> time-vector
2019-11-21 07:57:22 +00:00
11. Function - chronometrist-iso-date->timestamp (date)
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)
2019-11-21 07:50:21 +00:00
* event -> encode-time
*** chronometrist-timer.el
1. 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)
