diff --git a/README.md b/README.org similarity index 52% rename from README.md rename to README.org index 279c35e..bf4f40a 100644 --- a/README.md +++ b/README.org @@ -1,58 +1,62 @@ -# org-clock-waybar – Export the currently clocked-in task to be displayed on Waybar +#+TITLE: org-clock-waybar – Export the currently clocked-in task to be displayed on Waybar -## Installation +* Installation -Put `org-clock-waybar.el` somewhere in your `load-path`, and `(require 'org-clock-waybar)`. +Put ~org-clock-waybar.el~ somewhere in your ~load-path~, and ~(require 'org-clock-waybar)~. MELPA version may come soon. -You can set the file to be written by customizing `org-clock-waybar-filename`; it defaults to -`$XDG_CACHE_HOME/waybar-current-task.json` (`$XDG_CACHE_HOME` defaults to `$HOME/.cache` on XDG -compatible systems, like Linux.) +** Quelpa -### Quelpa +If you only have [[https://github.com/quelpa/quelpa][quelpa]] installed: -If you only have [`quelpa`](https://github.com/quelpa/quelpa) installed: - -```elisp +#+begin_src emacs-lisp (quelpa '(org-clock-waybar :fetcher git :url "https://gitea.polonkai.eu/gergely/org-clock-waybar.git")) -``` +#+end_src -or, if you have [`quelpa-use-package`](https://github.com/quelpa/quelpa-use-package) installed, +or, if you have [[https://github.com/quelpa/quelpa-use-package][quelpa-use-package] installed, too: -```elisp +#+begin_src emacs-lisp (quelpa-use-package org-clock-waybar :quelpa (org-clock-waybar :fetcher git :url "https://gitea.polonkai.eu/gergely/org-clock-waybar.git")) -``` +#+end_src -## Waybar configuration +* Customization + +To see a list of configurable parts, use ~M-x customize-group org-clock-waybar~. + +You can set the file to be written by customizing ~org-clock-waybar-filename~; it +defaults to ~$XDG_CACHE_HOME/waybar-current-task.json~ (~$XDG_CACHE_HOME~ defaults +to ~$HOME/.cache~ on XDG compatible systems, like Linux.) + +* Waybar configuration To add the current task to Waybar, add this snippet to your config: -```json +#+begin_src json "custom/org": { "format": " {}", "return-type": "json", "restart-interval": 5, "exec": "cat /home/yourusername/.cache/waybar-current-task.json" } -``` +#+end_src -Then, add `custom/org` to `modules-left`/`modules-center`/`module-right` if your bar’s -configuration. You can find a minimal working configuration in the [`examples`](./examples) -directory. +Then, add ~custom/org~ to your ~modules-left~, ~modules-center~, or ~module-right~ +section in your bar’s configuration. You can find a minimal working +configuration in the [[./examples][examples]] directory. -### Additional Configuration +** Additional Configuration -You can also display an icon specific to the clocked tasks category with the `format-icons` key: +You can also display an icon specific to the clocked tasks category with the ~format-icons~ key: -```json +#+begin_src json "custom/org": { "format": "{icon} {}", "return-type": "json", @@ -63,17 +67,17 @@ You can also display an icon specific to the clocked tasks category with the `fo }, "exec": "cat /home/yourusername/.cache/waybar-current-task.json" } -``` +#+end_src -If you use Emacs as a daemon (e.g. starting it as `emacs --daemon` or calling `(server-start)`), -you can change the `exec` command to invoke `emacsclient` directly. Note that, since Emacsclient -can’t actually write stuff to the terminal, it will output an Emacs string full of backslashes -(see [this Emacs SE answer for details](https://emacs.stackexchange.com/a/28668/507)); thus, you -have to pipe the output through `jq fromjson`. +If you use Emacs as a daemon (e.g. starting it as ~emacs --daemon~ or calling +~(server-start)~), you can change the ~exec~ command to invoke ~emacsclient~ directly. +Note that, since Emacsclient can’t actually write stuff to the terminal, it will +output an Emacs string full of backslashes (see [[https://emacs.stackexchange.com/a/28668/507][this Emacs SE answer for +details]]); thus, you have to pipe the output through ~jq fromjson~. If you run emacs in this mode you can also eval commands on click, middle click or scroll.: -```json +#+begin_src json "custom/org": { "format": "{icon} {}", "return-type": "json", @@ -86,19 +90,14 @@ If you run emacs in this mode you can also eval commands on click, middle click "on-click": "emacsclient --eval '(org-clock-out)'", "on-middle-click": "emacsclient --eval '(org-clock-in-last)'", }, - -``` +#+end_src If you want the taskbar to show nothing or some other content if the emacs server is not running then you need to write a short bash script to catch when the emacsclient command returns a non-zero exit code. An example of this is: -```bash +#+begin_src bash #!/bin/bash json=$(emacsclient --eval '(org-clock-waybar-ouptut-task)' 2> /dev/null) status=$? [ $status -eq 0 ] && echo $(echo $json | jq fromjson --unbuffered --compact-output) || echo "" -``` - -## Customization - -To see a list of configurable parts, use `M-x customize-group org-clock-waybar`. +#+end_src