Update README/manual
This commit is contained in:
contrapunctus
parent
07322c1052
commit
4ddc06c084
64
manual.md
64
manual.md
|
|
@ -13,7 +13,7 @@
|
|||
1. [chronometrist](#usage-chronometrist)
|
||||
2. [chronometrist-report](#usage-chronometrist-report)
|
||||
3. [chronometrist-statistics](#usage-chronometrist-statistics)
|
||||
4. [chronometrist-details](#org533cd01)
|
||||
4. [chronometrist-details](#org1c7a9d6)
|
||||
5. [common commands](#usage-common-commands)
|
||||
6. [Time goals/targets](#time-goals)
|
||||
6. [How-to](#how-to)
|
||||
|
|
@ -21,14 +21,14 @@
|
|||
2. [How to load the program using literate-elisp](#how-to-literate-elisp)
|
||||
3. [How to attach tags to time intervals](#how-to-tags)
|
||||
4. [How to attach key-values to time intervals](#how-to-key-value-pairs)
|
||||
5. [How to skip running hooks/attaching tags and key values](#org0e10cef)
|
||||
5. [How to skip running hooks/attaching tags and key values](#org5198d0f)
|
||||
6. [How to open certain files when you start a task](#how-to-open-files-on-task-start)
|
||||
7. [How to warn yourself about uncommitted changes](#how-to-warn-uncommitted-changes)
|
||||
8. [How to display the current time interval in the activity indicator](#how-to-activity-indicator)
|
||||
9. [How to back up your Chronometrist data](#how-to-backup)
|
||||
7. [Explanation](#orgd02a44a)
|
||||
7. [Explanation](#org32bb6b5)
|
||||
1. [Literate Program](#explanation-literate-program)
|
||||
8. [User's reference](#org215fb52)
|
||||
8. [User's reference](#orga4b321a)
|
||||
9. [Contributions and contact](#contributions-contact)
|
||||
10. [License](#license)
|
||||
11. [Thanks](#thanks)
|
||||
|
|
@ -51,15 +51,14 @@ Largely modelled after the Android application, [A Time Tracker](https://github.
|
|||
3. Support for both mouse and keyboard
|
||||
4. Human errors in tracking are easily fixed by editing a plain text file
|
||||
5. Hooks to let you perform arbitrary actions when starting/stopping tasks
|
||||
6. Fancy graphs with chronometrist-sparkline extension
|
||||
6. Fancy graphs with the `chronometrist-spark` extension
|
||||
|
||||
|
||||
<a id="limitations"></a>
|
||||
|
||||
# Limitations
|
||||
|
||||
1. No support (yet) for adding a task without clocking into it.
|
||||
2. No support for concurrent tasks.
|
||||
1. No support for concurrent tasks.
|
||||
|
||||
|
||||
<a id="comparisons"></a>
|
||||
|
|
@ -88,7 +87,6 @@ Chronometrist and Org time tracking seem to be equivalent in terms of capabiliti
|
|||
- Chronometrist doesn't have a mode line indicator at the moment. (planned)
|
||||
- Chronometrist doesn't have Org's sophisticated querying facilities. (an SQLite backend is planned)
|
||||
- Org does so many things that keybindings seem to necessarily get longer. Chronometrist has far fewer commands than Org, so most of the keybindings are single keys, without modifiers.
|
||||
- Chronometrist's UI makes keybindings discoverable - they are displayed in the buffers themselves.
|
||||
- Chronometrist's UI is cleaner, since the storage is separate from the display. It doesn't show tasks as trees like Org, but it uses tags and key-values to achieve that. Additionally, navigating a flat list takes fewer user operations than navigating a tree.
|
||||
- Chronometrist data is just s-expressions (plists), and may be easier to parse than a complex text format with numerous use-cases.
|
||||
|
||||
|
|
@ -103,7 +101,7 @@ Chronometrist and Org time tracking seem to be equivalent in terms of capabiliti
|
|||
## from MELPA
|
||||
|
||||
1. Set up MELPA - <https://melpa.org/#/getting-started>
|
||||
|
||||
|
||||
(Chronometrist uses Semantic Versioning and the developer is accident-prone, so using MELPA Stable is suggested 😏)
|
||||
2. `M-x package-install RET chronometrist RET`
|
||||
|
||||
|
|
@ -159,7 +157,7 @@ Run `M-x chronometrist-statistics` (or `chronometrist` with a prefix argument of
|
|||
Press `b` to look at past time ranges, and `f` for future ones.
|
||||
|
||||
|
||||
<a id="org533cd01"></a>
|
||||
<a id="org1c7a9d6"></a>
|
||||
|
||||
## chronometrist-details
|
||||
|
||||
|
|
@ -202,7 +200,7 @@ Evaluate or add to your init.el the following -
|
|||
## How to load the program using literate-elisp
|
||||
|
||||
(add-to-list 'load-path "<directory containing chronometrist.org>")
|
||||
|
||||
|
||||
(require 'literate-elisp) ;; or autoload, use-package, ...
|
||||
(literate-elisp-load "chronometrist.org")
|
||||
|
||||
|
|
@ -211,13 +209,13 @@ Evaluate or add to your init.el the following -
|
|||
|
||||
## How to attach tags to time intervals
|
||||
|
||||
1. Add `chronometrist-tags-add` to one or more of these hooks <sup><a id="fnr.1" class="footref" href="#fn.1">1</a></sup> -
|
||||
|
||||
1. Add `chronometrist-tags-add` to one or more of these hooks <sup><a id="fnr.1" class="footref" href="#fn.1" role="doc-backlink">1</a></sup> -
|
||||
|
||||
(add-to-list 'chronometrist-after-in-functions 'chronometrist-tags-add)
|
||||
(add-to-list 'chronometrist-before-out-functions 'chronometrist-tags-add)
|
||||
(add-to-list 'chronometrist-after-out-functions 'chronometrist-tags-add)
|
||||
2. clock in/clock out to trigger the hook.
|
||||
|
||||
|
||||
The prompt suggests past combinations you used for the current task, which you can browse with `M-p=/=M-n`. You can leave it blank by pressing `RET`.
|
||||
|
||||
|
||||
|
|
@ -225,7 +223,7 @@ Evaluate or add to your init.el the following -
|
|||
|
||||
## How to attach key-values to time intervals
|
||||
|
||||
1. Add `chronometrist-kv-add` to one or more of these hooks <sup><a id="fnr.2" class="footref" href="#fn.2">2</a></sup> -
|
||||
1. Add `chronometrist-kv-add` to one or more of these hooks <sup><a id="fnr.2" class="footref" href="#fn.2" role="doc-backlink">2</a></sup> -
|
||||
|
||||
(add-to-list 'chronometrist-after-in-functions 'chronometrist-kv-add)
|
||||
(add-to-list 'chronometrist-before-out-functions 'chronometrist-kv-add)
|
||||
|
|
@ -234,7 +232,7 @@ Evaluate or add to your init.el the following -
|
|||
To exit the prompt, press the key it indicates for quitting - you can then edit the resulting key-values by hand if required. Press `C-c C-c` to accept the key-values, or `C-c C-k` to cancel.
|
||||
|
||||
|
||||
<a id="org0e10cef"></a>
|
||||
<a id="org5198d0f"></a>
|
||||
|
||||
## How to skip running hooks/attaching tags and key values
|
||||
|
||||
|
|
@ -253,7 +251,7 @@ An idea from the author's own init -
|
|||
(find-file-other-window "~/repertoire.org"))
|
||||
;; ...
|
||||
))
|
||||
|
||||
|
||||
(add-hook 'chronometrist-before-in-functions 'my-start-project)
|
||||
|
||||
|
||||
|
|
@ -264,19 +262,19 @@ An idea from the author's own init -
|
|||
Another one, prompting the user if they have uncommitted changes in a git repository (assuming they use [Magit](https://magit.vc/)) -
|
||||
|
||||
(autoload 'magit-anything-modified-p "magit")
|
||||
|
||||
|
||||
(defun my-commit-prompt ()
|
||||
"Prompt user if `default-directory' is a dirty Git repository.
|
||||
Return t if the user answers yes, if the repository is clean, or
|
||||
if there is no Git repository.
|
||||
|
||||
|
||||
Return nil (and run `magit-status') if the user answers no."
|
||||
(cond ((not (magit-anything-modified-p)) t)
|
||||
((yes-or-no-p
|
||||
(format "You have uncommitted changes in %S. Really clock out? "
|
||||
default-directory)) t)
|
||||
(t (magit-status) nil)))
|
||||
|
||||
((yes-or-no-p
|
||||
(format "You have uncommitted changes in %S. Really clock out? "
|
||||
default-directory)) t)
|
||||
(t (magit-status) nil)))
|
||||
|
||||
(add-hook 'chronometrist-before-out-functions 'my-commit-prompt)
|
||||
|
||||
|
||||
|
|
@ -286,13 +284,13 @@ Another one, prompting the user if they have uncommitted changes in a git reposi
|
|||
|
||||
(defun my-activity-indicator ()
|
||||
(thread-last (plist-put (chronometrist-last)
|
||||
:stop (chronometrist-format-time-iso8601))
|
||||
:stop (chronometrist-format-time-iso8601))
|
||||
list
|
||||
chronometrist-events-to-durations
|
||||
(-reduce #'+)
|
||||
truncate
|
||||
chronometrist-format-time))
|
||||
|
||||
|
||||
(setq chronometrist-activity-indicator #'my-activity-indicator)
|
||||
|
||||
|
||||
|
|
@ -303,16 +301,16 @@ Another one, prompting the user if they have uncommitted changes in a git reposi
|
|||
I suggest backing up Chronometrist data on each save. Here's how you can do that.
|
||||
|
||||
1. Add the following to your init.
|
||||
|
||||
|
||||
(setq backup-by-copying t
|
||||
kept-new-versions 10
|
||||
kept-old-versions 10
|
||||
version-control t)
|
||||
|
||||
|
||||
(defun my-force-backup ()
|
||||
(setq buffer-backed-up nil))
|
||||
2. Open your Chronometrist file and add the function to `before-save-hook`.
|
||||
|
||||
|
||||
M-x chronometrist-open-log
|
||||
M-x add-file-local-variable-prop-line RET eval RET (add-hook 'before-save-hook #'my-force-backup nil t) RET
|
||||
3. Optionally, configure `backup-directory-alist` to set a specific directory for the backups.
|
||||
|
|
@ -320,7 +318,7 @@ I suggest backing up Chronometrist data on each save. Here's how you can do that
|
|||
Adapted from this [StackOverflow answer](https://stackoverflow.com/questions/6916529/how-can-i-make-emacs-backup-every-time-i-save).
|
||||
|
||||
|
||||
<a id="orgd02a44a"></a>
|
||||
<a id="org32bb6b5"></a>
|
||||
|
||||
# Explanation
|
||||
|
||||
|
|
@ -336,7 +334,7 @@ The Org file can also be loaded directly using the [literate-elisp](https://gi
|
|||
`chronometrist.org` is also included in MELPA installs, although not used directly by default, since doing so would interfere with automatic generation of autoloads.
|
||||
|
||||
|
||||
<a id="org215fb52"></a>
|
||||
<a id="orga4b321a"></a>
|
||||
|
||||
# User's reference
|
||||
|
||||
|
|
@ -393,7 +391,7 @@ I'd rather make a request - please do everything you can to help that dream come
|
|||
|
||||
Chronometrist is released under your choice of [Unlicense](https://unlicense.org/) or the [WTFPL](http://www.wtfpl.net/).
|
||||
|
||||
(See files <UNLICENSE> and <WTFPL>).
|
||||
(See files [UNLICENSE](UNLICENSE) and [WTFPL](WTFPL)).
|
||||
|
||||
|
||||
<a id="thanks"></a>
|
||||
|
|
@ -402,7 +400,7 @@ Chronometrist is released under your choice of [Unlicense](https://unlicense.org
|
|||
|
||||
wasamasa, bpalmer, aidalgol, pjb and the rest of #emacs for their tireless help and support
|
||||
|
||||
jwiegley for timeclock.el, which we used as a backend in earlier versions
|
||||
jwiegley for `timeclock.el`, which we used as a backend in earlier versions
|
||||
|
||||
blandest for helping me with the name
|
||||
|
||||
|
|
|
|||
14
manual.org
14
manual.org
|
|
@ -22,14 +22,13 @@ Largely modelled after the Android application, [[https://github.com/netmackan/A
|
|||
3. Support for both mouse and keyboard
|
||||
4. Human errors in tracking are easily fixed by editing a plain text file
|
||||
5. Hooks to let you perform arbitrary actions when starting/stopping tasks
|
||||
6. Fancy graphs with chronometrist-sparkline extension
|
||||
6. Fancy graphs with the =chronometrist-spark= extension
|
||||
|
||||
* Limitations
|
||||
:PROPERTIES:
|
||||
:CUSTOM_ID: limitations
|
||||
:END:
|
||||
1. No support (yet) for adding a task without clocking into it.
|
||||
2. No support for concurrent tasks.
|
||||
1. No support for concurrent tasks.
|
||||
|
||||
* Comparisons
|
||||
:PROPERTIES:
|
||||
|
|
@ -55,7 +54,6 @@ Chronometrist and Org time tracking seem to be equivalent in terms of capabiliti
|
|||
+ Chronometrist doesn't have a mode line indicator at the moment. (planned)
|
||||
+ Chronometrist doesn't have Org's sophisticated querying facilities. (an SQLite backend is planned)
|
||||
+ Org does so many things that keybindings seem to necessarily get longer. Chronometrist has far fewer commands than Org, so most of the keybindings are single keys, without modifiers.
|
||||
+ Chronometrist's UI makes keybindings discoverable - they are displayed in the buffers themselves.
|
||||
+ Chronometrist's UI is cleaner, since the storage is separate from the display. It doesn't show tasks as trees like Org, but it uses tags and key-values to achieve that. Additionally, navigating a flat list takes fewer user operations than navigating a tree.
|
||||
+ Chronometrist data is just s-expressions (plists), and may be easier to parse than a complex text format with numerous use-cases.
|
||||
|
||||
|
|
@ -353,7 +351,7 @@ I'd rather make a request - please do everything you can to help that dream come
|
|||
|
||||
Chronometrist is released under your choice of [[https://unlicense.org/][Unlicense]] or the [[http://www.wtfpl.net/][WTFPL]].
|
||||
|
||||
(See files [[file:UNLICENSE]] and [[file:WTFPL]]).
|
||||
(See files [[file:UNLICENSE][UNLICENSE]] and [[file:WTFPL][WTFPL]]).
|
||||
|
||||
* Thanks
|
||||
:PROPERTIES:
|
||||
|
|
@ -362,8 +360,12 @@ Chronometrist is released under your choice of [[https://unlicense.org/][Unlicen
|
|||
|
||||
wasamasa, bpalmer, aidalgol, pjb and the rest of #emacs for their tireless help and support
|
||||
|
||||
jwiegley for timeclock.el, which we used as a backend in earlier versions
|
||||
jwiegley for =timeclock.el=, which we used as a backend in earlier versions
|
||||
|
||||
blandest for helping me with the name
|
||||
|
||||
fiete and wu-lee for testing and bug reports
|
||||
|
||||
# Local Variables:
|
||||
# eval: (progn (require 'ox-md) (add-hook 'after-save-hook (lambda () (org-export-to-file 'md "manual.md")) nil t))
|
||||
# End:
|
||||
|
|
|
|||
Reference in New Issue