This repository has been archived on 2022-05-13. You can view files and clone it, but cannot push or open issues or pull requests.
chronometrist/doc/manual.info

709 lines
18 KiB
Plaintext

\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename manual.info
@settitle The Chronometrist Manual
@documentencoding UTF-8
@documentlanguage en
@c %**end of header
@finalout
@titlepage
@title The Chronometrist Manual
@author contrapunctus
@end titlepage
@contents
@ifnottex
@node Top
@top The Chronometrist Manual
The structure of this manual was inspired by @uref{https://documentation.divio.com/}
@end ifnottex
@menu
* How to@dots{}:: Step-by-step guides to achieve specific tasks
* Reference:: A list of definitions, with some type information
@detailmenu
--- The Detailed Node Listing ---
How to@dots{}
* How to set up Emacs to contribute::
Reference
* chronometrist-common.el: chronometrist-commonel.
* chronometrist-custom.el: chronometrist-customel.
* chronometrist-diary-view.el: chronometrist-diary-viewel.
* chronometrist.el: chronometristel.
* chronometrist-events.el: chronometrist-eventsel.
* chronometrist-migrate.el: chronometrist-migrateel.
* chronometrist-plist-pp.el: chronometrist-plist-ppel.
* chronometrist-queries.el: chronometrist-queriesel.
* chronometrist-report-custom.el: chronometrist-report-customel.
* chronometrist-report.el: chronometrist-reportel.
* chronometrist-key-values.el: chronometrist-key-valuesel.
* chronometrist-statistics-custom.el: chronometrist-statistics-customel.
* chronometrist-statistics.el: chronometrist-statisticsel.
* chronometrist-time.el: chronometrist-timeel.
* chronometrist-timer.el: chronometrist-timerel.
* chronometrist-goal::
* chronometrist-sexp::
@end detailmenu
@end menu
@node How to@dots{}
@chapter How to@dots{}
@menu
* How to set up Emacs to contribute::
@end menu
@node How to set up Emacs to contribute
@section How to set up Emacs to contribute
All of these are optional, but recommended for the best experience.
@enumerate
@item
Use @uref{https://github.com/Malabarba/Nameless, nameless-mode} for easier reading of Emacs Lisp code, and
@item
Use @uref{https://github.com/joostkremers/visual-fill-column, visual-fill-column-mode} to soft-wrap lines in Org/Markdown files.
@samp{org-indent-mode} (for Org files) and @uref{https://elpa.gnu.org/packages/adaptive-wrap.html, adaptive-prefix-mode} (for Markdown and other files) will further enhance the experience.
@item
Get the sources from @uref{https://github.com/contrapunctus-1/chronometrist} and read this manual in the Org format (doc/manual.org), so links to identifiers can take you to their location in the source.
@item
Install @uref{https://github.com/cask/cask, Cask} to easily byte-compile and test the project.
From the project root, you can now run
@enumerate
@item
@samp{cask} to install the project dependencies in a sandbox
@item
@samp{cask exec buttercup -L . --traceback pretty} to run tests.
@end enumerate
@end enumerate
@node Reference
@chapter Reference
@menu
* chronometrist-common.el: chronometrist-commonel.
* chronometrist-custom.el: chronometrist-customel.
* chronometrist-diary-view.el: chronometrist-diary-viewel.
* chronometrist.el: chronometristel.
* chronometrist-events.el: chronometrist-eventsel.
* chronometrist-migrate.el: chronometrist-migrateel.
* chronometrist-plist-pp.el: chronometrist-plist-ppel.
* chronometrist-queries.el: chronometrist-queriesel.
* chronometrist-report-custom.el: chronometrist-report-customel.
* chronometrist-report.el: chronometrist-reportel.
* chronometrist-key-values.el: chronometrist-key-valuesel.
* chronometrist-statistics-custom.el: chronometrist-statistics-customel.
* chronometrist-statistics.el: chronometrist-statisticsel.
* chronometrist-time.el: chronometrist-timeel.
* chronometrist-timer.el: chronometrist-timerel.
* chronometrist-goal::
* chronometrist-sexp::
@end menu
@node chronometrist-commonel
@section chronometrist-common.el
@enumerate
@item
Variable - chronometrist-task-list
@item
Internal Variable - chronometrist--fs-watch
@item
Function - chronometrist-current-task ()
@item
Function - chronometrist-format-time (seconds &optional (blank " "))
@itemize
@item
seconds -> "h:m:s"
@end itemize
@item
Function - chronometrist-common-file-empty-p (file)
@item
Function - chronometrist-common-clear-buffer (buffer)
@item
Function - chronometrist-format-keybinds (command map &optional firstonly)
@item
Function - chronometrist-events->ts-pairs (events)
@itemize
@item
(plist @dots{}) -> ((ts . ts) @dots{})
@end itemize
@item
Function - chronometrist-ts-pairs->durations (ts-pairs)
@itemize
@item
((ts . ts) @dots{}) -> seconds
@end itemize
@item
Function - chronometrist-previous-week-start (ts)
@itemize
@item
ts -> ts
@end itemize
@end enumerate
@node chronometrist-customel
@section chronometrist-custom.el
@enumerate
@item
Custom variable - chronometrist-file
@item
Custom variable - chronometrist-buffer-name
@item
Custom variable - chronometrist-hide-cursor
@item
Custom variable - chronometrist-update-interval
@item
Custom variable - chronometrist-activity-indicator
@item
Custom variable - chronometrist-day-start-time
@end enumerate
@node chronometrist-diary-viewel
@section chronometrist-diary-view.el
@enumerate
@item
Variable - chronometrist-diary-buffer-name
@item
Internal Variable - chronometrist-diary--current-date
@item
Function - chronometrist-intervals-on (date)
@item
Function - chronometrist-diary-tasks-reasons-on (date)
@item
Function - chronometrist-diary-refresh (&optional ignore-auto noconfirm date)
@item
Major Mode - chronometrist-diary-view-mode
@item
Command - chronometrist-diary-view (&optional date)
@end enumerate
@node chronometristel
@section chronometrist.el
@enumerate
@item
Internal Variable - chronometrist--point
@item
Keymap - chronometrist-mode-map
@item
Command - chronometrist-open-log (&optional button)
@item
Function - chronometrist-common-create-file ()
@item
Function - chronometrist-task-active? (task)
@itemize
@item
String -> Boolean
@end itemize
@item
Function - chronometrist-use-goals? ()
@item
Function - chronometrist-run-transformers (transformers arg)
@item
Function - chronometrist-activity-indicator ()
@item
Function - chronometrist-entries ()
@item
Function - chronometrist-task-at-point ()
@item
Function - chronometrist-goto-last-task ()
@item
Function - chronometrist-print-keybind (command &optional description firstonly)
@item
Function - chronometrist-print-non-tabular ()
@item
Function - chronometrist-goto-nth-task (n)
@item
Function - chronometrist-refresh (&optional ignore-auto noconfirm)
@item
Internal Variable - chronometrist--file-state
@item
Function - chronometrist-file-hash (&optional start end hash)
@item
Function - chronometrist-read-from (position)
@item
Function - chronometrist-file-change-type (state)
@item
Function - chronometrist-task-list ()
@itemize
@item
-> List
@end itemize
@item
Function - chronometrist-reset-task-list ()
@item
Function - chronometrist-add-to-task-list (task)
@item
Function - chronometrist-remove-from-task-list (task)
@item
Function - chronometrist-refresh-file (fs-event)
@item
Command - chronometrist-query-stop ()
@item
Command - chronometrist-in (task &optional _prefix)
@item
Command - chronometrist-out (&optional _prefix)
@item
Variable - chronometrist-before-in-functions
@item
Variable - chronometrist-after-in-functions
@item
Variable - chronometrist-before-out-functions
@item
Variable - chronometrist-after-out-functions
@item
Function - chronometrist-run-functions-and-clock-in (task)
@item
Function - chronometrist-run-functions-and-clock-out (task)
@item
Keymap - chronometrist-mode-map
@item
Major Mode - chronometrist-mode
@item
Function - chronometrist-toggle-task-button (button)
@item
Function - chronometrist-add-new-task-button (button)
@item
Command - chronometrist-toggle-task (&optional prefix inhibit-hooks)
@item
Command - chronometrist-toggle-task-no-hooks (&optional prefix)
@item
Command - chronometrist-add-new-task ()
@item
Command - chronometrist (&optional arg)
@end enumerate
@node chronometrist-eventsel
@section chronometrist-events.el
@enumerate
@item
Variable - chronometrist-events
@itemize
@item
keys - iso-date
@end itemize
@item
Function - chronometrist-day-start (timestamp)
@itemize
@item
iso-timestamp -> encode-time
@end itemize
@item
Function - chronometrist-file-clean ()
@itemize
@item
commented out, unused
@end itemize
@item
Function - chronometrist-events-maybe-split (event)
@item
Function - chronometrist-events-populate ()
@item
Function - chronometrist-events-update (plist &optional replace)
@item
Function - chronometrist-events-subset (start end)
@itemize
@item
ts ts -> hash-table
@end itemize
@end enumerate
@node chronometrist-migrateel
@section chronometrist-migrate.el
@enumerate
@item
Variable - chronometrist-migrate-table
@item
Function - chronometrist-migrate-populate (in-file)
@item
Function - chronometrist-migrate-timelog-file->sexp-file (&optional in-file out-file)
@item
Function - chronometrist-migrate-check ()
@end enumerate
@node chronometrist-plist-ppel
@section chronometrist-plist-pp.el
@enumerate
@item
Variable - chronometrist-plist-pp-keyword-re
@item
Variable - chronometrist-plist-pp-whitespace-re
@item
Function - chronometrist-plist-pp-longest-keyword-length ()
@item
Function - chronometrist-plist-pp-buffer-keyword-helper ()
@item
Function - chronometrist-plist-pp-buffer ()
@item
Function - chronometrist-plist-pp-to-string (object)
@item
Function - chronometrist-plist-pp (object &optional stream)
@end enumerate
@node chronometrist-queriesel
@section chronometrist-queries.el
@enumerate
@item
Function - chronometrist-last ()
@itemize
@item
-> plist
@end itemize
@item
Function - chronometrist-task-time-one-day (task &optional (ts (ts-now)))
@itemize
@item
String &optional ts -> seconds
@end itemize
@item
Function - chronometrist-active-time-one-day (&optional (ts (ts-now)))
@itemize
@item
&optional ts -> seconds
@end itemize
@item
Function - chronometrist-statistics-count-active-days (task &optional (table chronometrist-events))
@item
Function - chronometrist-task-events-in-day (task &optional (ts (ts-now)))
@end enumerate
@node chronometrist-report-customel
@section chronometrist-report-custom.el
@enumerate
@item
Custom variable - chronometrist-report-buffer-name
@item
Custom variable - chronometrist-report-week-start-day
@item
Custom variable - chronometrist-report-weekday-number-alist
@end enumerate
@node chronometrist-reportel
@section chronometrist-report.el
@enumerate
@item
Internal Variable - chronometrist-report--ui-date
@item
Internal Variable - chronometrist-report--ui-week-dates
@item
Internal Variable - chronometrist-report--point
@item
Function - chronometrist-report-date ()
@item
Function - chronometrist-report-date->dates-in-week (first-date-in-week)
@itemize
@item
ts-1 -> (ts-1 @dots{} ts-7)
@end itemize
@item
Function - chronometrist-report-date->week-dates ()
@item
Function - chronometrist-report-entries ()
@item
Function - chronometrist-report-print-keybind (command &optional description firstonly)
@item
Function - chronometrist-report-print-non-tabular ()
@item
Function - chronometrist-report-refresh (&optional _ignore-auto _noconfirm)
@item
Function - chronometrist-report-refresh-file (@math{_fs}-event)
@item
Keymap - chronometrist-report-mode-map
@item
Major Mode - chronometrist-report-mode
@item
Function - chronometrist-report (&optional keep-date)
@item
Function - chronometrist-report-previous-week (arg)
@item
Function - chronometrist-report-next-week (arg)
@end enumerate
@node chronometrist-key-valuesel
@section chronometrist-key-values.el
@enumerate
@item
Internal Variable - chronometrist--tag-suggestions
@item
Internal Variable - chronometrist--value-suggestions
@item
Function - chronometrist-plist-remove (plist &rest keys)
@item
Function - chronometrist-maybe-string-to-symbol (list)
@item
Function - chronometrist-maybe-symbol-to-string (list)
@item
Function - chronometrist-append-to-last (tags plist)
@item
Variable - chronometrist-tags-history
@item
Function - chronometrist-history-prep (key history-table)
@item
Function - chronometrist-tags-history-populate (task history-table file)
@item
Function - chronometrist-key-history-populate (task history-table file)
@item
Function - chronometrist-value-history-populate (history-table file)
@item
Function - chronometrist-tags-history-add (plist)
@item
Function - chronometrist-tags-history-combination-strings (task)
@item
Function - chronometrist-tags-history-individual-strings (task)
@item
Function - chronometrist-tags-prompt (task &optional initial-input)
@item
Function - chronometrist-tags-add (&rest args)
@item
Custom Variable - chronometrist-kv-buffer-name
@item
Variable - chronometrist-key-history
@item
Variable - chronometrist-value-history
@item
Keymap - chronometrist-kv-read-mode-map
@item
Major Mode - chronometrist-kv-read-mode
@item
Function - chronometrist-kv-completion-quit-key ()
@item
Function - chronometrist-string-has-whitespace-p (string)
@item
Function - chronometrist-key-prompt (used-keys)
@item
Function - chronometrist-value-prompt (key)
@item
Function - chronometrist-value-insert (value)
@item
Function - chronometrist-kv-add (&rest args)
@item
Command - chronometrist-kv-accept ()
@item
Command - chronometrist-kv-reject ()
@item
Internal Variable - chronometrist--skip-detail-prompts
@item
Function - chronometrist-skip-query-prompt (task)
@item
Function - chronometrist-skip-query-reset (@math{_task})
@end enumerate
@node chronometrist-statistics-customel
@section chronometrist-statistics-custom.el
@enumerate
@item
Custom variable - chronometrist-statistics-buffer-name
@end enumerate
@node chronometrist-statisticsel
@section chronometrist-statistics.el
@enumerate
@item
Internal Variable - chronometrist-statistics--ui-state
@item
Internal Variable - chronometrist-statistics--point
@item
Function - chronometrist-statistics-count-average-time-spent (task &optional (table chronometrist-events))
@itemize
@item
string &optional hash-table -> seconds
@end itemize
@item
Function - chronometrist-statistics-entries-internal (table)
@item
Function - chronometrist-statistics-entries ()
@item
Function - chronometrist-statistics-print-keybind (command &optional description firstonly)
@item
Function - chronometrist-statistics-print-non-tabular ()
@item
Function - chronometrist-statistics-refresh (&optional ignore-auto noconfirm)
@item
Keymap - chronometrist-statistics-mode-map
@item
Major Mode - chronometrist-statistics-mode
@item
Command - chronometrist-statistics (&optional preserve-state)
@item
Command - chronometrist-statistics-previous-range (arg)
@item
Command - chronometrist-statistics-next-range (arg)
@end enumerate
@node chronometrist-timeel
@section chronometrist-time.el
@enumerate
@item
Function - chronometrist-iso-timestamp->ts (timestamp)
@itemize
@item
iso-timestamp -> ts
@end itemize
@item
Function - chronometrist-iso-date->ts (date)
@itemize
@item
iso-date -> ts
@end itemize
@item
Function - chronometrist-date (&optional (ts (ts-now)))
@itemize
@item
&optional ts -> ts (with time 00:00:00)
@end itemize
@item
Function - chronometrist-format-time-iso8601 (&optional unix-time)
@item
Function - chronometrist-midnight-spanning-p (start-time stop-time)
@item
Function - chronometrist-seconds-to-hms (seconds)
@itemize
@item
seconds -> list-duration
@end itemize
@item
Function - chronometrist-interval (event)
@itemize
@item
event -> duration
@end itemize
@end enumerate
@node chronometrist-timerel
@section chronometrist-timer.el
@enumerate
@item
Internal Variable - chronometrist--timer-object
@item
Function - chronometrist-timer ()
@item
Command - chronometrist-stop-timer ()
@item
Command - chronometrist-maybe-start-timer (&optional interactive-test)
@item
Command - chronometrist-force-restart-timer ()
@item
Command - chronometrist-change-update-interval (arg)
@end enumerate
@node chronometrist-goal
@section chronometrist-goal
@enumerate
@item
Internal Variable - chronometrist-goal--timers-list
@item
Custom Variable - chronometrist-goal-list nil
@item
Function - chronometrist-goal-run-at-time (time repeat function &rest args)
@item
Function - chronometrist-goal-seconds->alert-string (seconds)
@itemize
@item
seconds -> string
@end itemize
@item
Function - chronometrist-goal-approach-alert (task goal spent)
@itemize
@item
string minutes minutes
@end itemize
@item
Function - chronometrist-goal-complete-alert (task goal spent)
@itemize
@item
string minutes minutes
@end itemize
@item
Function - chronometrist-goal-exceed-alert (task goal spent)
@itemize
@item
string minutes minutes
@end itemize
@item
Function - chronometrist-goal-no-goal-alert (task goal spent)
@itemize
@item
string minutes minutes
@end itemize
@item
Custom Variable - chronometrist-goal-alert-functions
@itemize
@item
each function is passed - string minutes minutes
@end itemize
@item
Function - chronometrist-goal-get (task &optional (goal-list chronometrist-goal-list))
@itemize
@item
String &optional List -> minutes
@end itemize
@item
Function - chronometrist-goal-run-alert-timers (task)
@item
Function - chronometrist-goal-stop-alert-timers (&optional _task)
@item
Function - chronometrist-goal-on-file-change ()
@end enumerate
@node chronometrist-sexp
@section chronometrist-sexp
@enumerate
@item
Custom variable - chronometrist-sexp-pretty-print-function
@item
Macro - chronometrist-sexp-in-file (file &rest body)
@item
Macro - chronometrist-loop-file (for expr in file &rest loop-clauses)
@item
Function - chronometrist-sexp-open-log ()
@item
Function - chronometrist-sexp-between (&optional (ts-beg (chronometrist-date)) (ts-end (ts-adjust 'day +1 (chronometrist-date))))
@item
Function - chronometrist-sexp-query-till (&optional (date (chronometrist-date)))
@item
Function - chronometrist-sexp-last ()
@itemize
@item
-> plist
@end itemize
@item
Function - chronometrist-sexp-current-task ()
@item
Function - chronometrist-sexp-events-populate ()
@item
Function - chronometrist-sexp-create-file ()
@item
Function - chronometrist-sexp-new (plist &optional (buffer (find-file-noselect chronometrist-file)))
@item
Function - chronometrist-sexp-delete-list (&optional arg)
@item
Function - chronometrist-sexp-replace-last (plist)
@item
Command - chronometrist-sexp-reindent-buffer ()
@end enumerate
@bye