From 524ba9592fc7095209e380392915b376f75bec00 Mon Sep 17 00:00:00 2001 From: contrapunctus Date: Tue, 13 Jul 2021 23:25:30 +0530 Subject: [PATCH] doc(README): add Liberapay widget, graph USP --- README.md | 1 + README.org | 1 - manual.md | 391 +++++++++++++++++++++++++++++++++++++++++++++++++++++ manual.org | 7 +- 4 files changed, 398 insertions(+), 2 deletions(-) create mode 120000 README.md delete mode 120000 README.org create mode 100644 manual.md diff --git a/README.md b/README.md new file mode 120000 index 0000000..9d0493a --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +manual.md \ No newline at end of file diff --git a/README.org b/README.org deleted file mode 120000 index e3c17fe..0000000 --- a/README.org +++ /dev/null @@ -1 +0,0 @@ -manual.org \ No newline at end of file diff --git a/manual.md b/manual.md new file mode 100644 index 0000000..a70aaba --- /dev/null +++ b/manual.md @@ -0,0 +1,391 @@ + +# Table of Contents + +1. [Benefits](#org83c3199) +2. [Limitations](#org265ad3f) +3. [Comparisons](#comparisons) + 1. [timeclock.el](#timeclock.el) + 2. [Org time tracking](#org-time-tracking) +4. [Installation](#installation) + 1. [from MELPA](#install-from-melpa) + 2. [from Git](#install-from-git) +5. [Usage](#usage) + 1. [chronometrist](#chronometrist-1) + 2. [chronometrist-report](#chronometrist-report) + 3. [chronometrist-statistics](#chronometrist-statistics) + 4. [chronometrist-details](#org0ec335b) + 5. [common commands](#org170f814) + 6. [Time goals/targets](#time-goalstargets) +6. [How-to](#customization) + 1. [How to display a prompt when exiting with an active task](#prompt-when-exiting-emacs) + 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](#org7fd0f91) + 6. [How to open certain files when you start a task](#open-certain-files-when-you-start-a-task) + 7. [How to warn yourself about uncommitted changes](#uncommitted-changes) + 8. [How to display the current time interval in the activity indicator](#current-time-interval-in-activity-indicator) +7. [Explanation](#orga5e2e2e) + 1. [Literate Program](#explanation-literate-program) +8. [User's reference](#org2c64088) +9. [Contributions and contact](#contributions-and-contact) +10. [License](#license) +11. [Thanks](#thanks) + +Donate using Liberapay + + + +A time tracker in Emacs with a nice interface + +Largely modelled after the Android application, [A Time Tracker](https://github.com/netmackan/ATimeTracker) + + + + +# Benefits + +1. Extremely simple and efficient to use +2. Displays useful information about your time usage +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 + + + + +# Limitations + +1. No support (yet) for adding a task without clocking into it. +2. No support for concurrent tasks. + + + + +# Comparisons + + + + +## timeclock.el + +Compared to timeclock.el, Chronometrist + +- stores data in an s-expression format rather than a line-based one +- supports attaching tags and arbitrary key-values to time intervals +- has commands to shows useful summaries +- has more hooks + + + + +## Org time tracking + +Chronometrist and Org time tracking seem to be equivalent in terms of capabilities, approaching the same ends through different means. + +- 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. + + + + +# Installation + + + + +## from MELPA + +1. Set up MELPA - + + (Chronometrist uses Semantic Versioning and the developer is accident-prone, so using MELPA Stable is suggested ๐Ÿ˜) +2. `M-x package-install RET chronometrist RET` + + + + +## from Git + +You can get `chronometrist` from + +`chronometrist` requires + +- Emacs v25 or higher +- [dash.el](https://github.com/magnars/dash.el) +- [ts.el](https://github.com/alphapapa/ts.el) + +Add the "elisp/" subdirectory to your load-path, and `(require 'chronometrist)`. + + + + +# Usage + + + + +## chronometrist + +Run `M-x chronometrist` to see your projects, the time you spent on them today, which one is active, and the total time clocked today. + +Click or hit `RET` (`chronometrist-toggle-task`) on a project to start tracking time for it. If it's already clocked in, it will be clocked out. + +You can also hit ` RET` anywhere in the buffer to toggle the corresponding project, e.g.ย =C-1 RET= will toggle the project with index 1. + +Press `r` to see a weekly report (see `chronometrist-report`) + + + + +## chronometrist-report + +Run `M-x chronometrist-report` (or `chronometrist` with a prefix argument of 1, or press `r` in the `chronometrist` buffer) to see a weekly report. + +Press `b` to look at past weeks, and `f` for future weeks. + + + + +## chronometrist-statistics + +Run `M-x chronometrist-statistics` (or `chronometrist` with a prefix argument of 2) to view statistics. + +Press `b` to look at past time ranges, and `f` for future ones. + + + + +## chronometrist-details + + + + +## common commands + +In the buffers created by the previous three commands, you can press `l` (`chronometrist-open-log`) to view/edit your `chronometrist-file`, which by default is `~/.emacs.d/chronometrist.sexp`. + +All of these commands will kill their buffer when run again with the buffer visible, so the keys you bind them to behave as a toggle. + +All buffers keep themselves updated via an idle timer - no need to frequently press `g` to update. + + + + +## Time goals/targets + +If you wish you could define time goals for some tasks, and have Chronometrist notify you when you're approaching the goal, completing it, or exceeding it, check out the extension [chronometrist-goal.el](https://github.com/contrapunctus-1/chronometrist-goal/). + + + + +# How-to + +See the Customize groups `chronometrist` and `chronometrist-report` for variables intended to be user-customizable. + + + + +## How to display a prompt when exiting with an active task + +Evaluate or add to your init.el the following - +`(add-hook 'kill-emacs-query-functions 'chronometrist-query-stop)` + + + + +## How to load the program using literate-elisp + + (add-to-list 'load-path "") + + (require 'literate-elisp) ;; or autoload, use-package, ... + (literate-elisp-load "chronometrist.org") + + + + +## How to attach tags to time intervals + +1. Add `chronometrist-tags-add` to one or more of these hooks 1 - + + (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`. + + + + +## How to attach key-values to time intervals + +1. Add `chronometrist-kv-add` to one or more of these hooks 2 - + + (add-to-list 'chronometrist-after-in-functions 'chronometrist-kv-add) + (add-to-list 'chronometrist-before-out-functions 'chronometrist-kv-add) + (add-to-list 'chronometrist-after-out-functions 'chronometrist-kv-add) + +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. + + + + +## How to skip running hooks/attaching tags and key values + +Use `M-RET` (`chronometrist-toggle-task-no-hooks`) to clock in/out. + + + + +## How to open certain files when you start a task + +An idea from the author's own init - + + (defun my-start-project (project) + (pcase project + ("Guitar" + (find-file-other-window "~/repertoire.org")) + ;; ... + )) + + (add-hook 'chronometrist-before-in-functions 'my-start-project) + + + + +## How to warn yourself about uncommitted changes + +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))) + + (add-hook 'chronometrist-before-out-functions 'my-commit-prompt) + + + + +## How to display the current time interval in the activity indicator + + (defun my-activity-indicator () + (thread-last (plist-put (chronometrist-last) + :stop (chronometrist-format-time-iso8601)) + list + chronometrist-events-to-durations + (-reduce #'+) + truncate + chronometrist-format-time)) + + (setq chronometrist-activity-indicator #'my-activity-indicator) + + + + +# Explanation + + + + +## Literate Program + +Chronometrist is a literate program, made using Org - the canonical source is the `chronometrist.org` file, which contains source blocks. These are provided to users after *tangling* (extracting the source into an Emacs Lisp file). + +The Org file can also be loaded directly using the [literate-elisp](https://github.com/jingtaozf/literate-elisp) package, so that all source links (e.g. `xref`, `describe-function`) lead to the Org file, within the context of the concerned documentation. See [How to load the program using literate-elisp](#how-to-literate-elisp). + +`chronometrist.org` is also included in MELPA installs, although not used directly by default, since doing so would interfere with automatic generation of autoloads. + + + + +# User's reference + +All variables intended for user customization are listed here. They serve as the public API for this project for the purpose of semantic versioning. Any changes to these which require a user to modify their configuration are considered breaking changes. + +1. `chronometrist-file` +2. `chronometrist-buffer-name` +3. `chronometrist-report-buffer-name` +4. `chronometrist-details-buffer-name` +5. `chronometrist-sexp-pretty-print-function` +6. `chronometrist-hide-cursor` +7. `chronometrist-update-interval` +8. `chronometrist-activity-indicator` + +Buffer schemas + +1. `chronometrist-schema` +2. `chronometrist-details-schema` + +Hooks + +1. `chronometrist-mode-hook` +2. `chronometrist-schema-transformers` +3. `chronometrist-row-transformers` +4. `chronometrist-before-in-functions` +5. `chronometrist-after-in-functions` +6. `chronometrist-before-out-functions` +7. `chronometrist-after-out-functions` +8. `chronometrist-file-change-hook` +9. `chronometrist-timer-hook` + + + + +# Contributions and contact + +Feedback and MRs are very welcome. ๐Ÿ™‚ + +- has a long list of tasks +- contains an overview of the codebase, explains various mechanisms and decisions, and has a reference of definitions. + +If you have tried using Chronometrist, I'd love to hear your experiences! Get in touch with the author and other Emacs users in the Emacs channel on the Jabber network - [xmpp:emacs@salas.suchat.org?join](https://conversations.im/j/emacs@salas.suchat.org) ([web chat](https://inverse.chat/#converse/room?jid=emacs@salas.suchat.org)) + +(For help in getting started with Jabber, [click here](https://xmpp.org/getting-started/)) + + + + +# License + +I dream of a world where all software is liberated - transparent, trustable, and accessible for anyone to use or improve. But I don't want to make demands or threats (e.g.ย via legal conditions) to get there. + +I'd rather make a request - please do everything you can to help that dream come true. Please Unlicense as much software as you can. + +Chronometrist is released under your choice of [Unlicense](https://unlicense.org/) or the [WTFPL](http://www.wtfpl.net/). + +(See files and ). + + + + +# Thanks + +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 + +blandest for helping me with the name + +fiete and wu-lee for testing and bug reports + + +# Footnotes + +1 but not `chronometrist-before-in-functions` + +2 but not `chronometrist-before-in-functions` diff --git a/manual.org b/manual.org index 2dd82aa..85ef385 100644 --- a/manual.org +++ b/manual.org @@ -2,7 +2,11 @@ #+SUBTITLE: User Manual #+HTML_HEAD: -[[https://melpa.org/#/chronometrist][file:https://melpa.org/packages/chronometrist-badge.svg]] +#+BEGIN_EXPORT html +Donate using Liberapay + + +#+END_EXPORT A time tracker in Emacs with a nice interface @@ -14,6 +18,7 @@ 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 * Limitations 1. No support (yet) for adding a task without clocking into it.