gergely/org-clock-waybar
1
0
Fork 1
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

Redesign README to become an Org document

Browse Source 
Why would we use markdown in the Emacs world, right?
This commit is contained in:
Gergely Polonkai 2023-10-27 05:47:59 +02:00
parent c327eb18c6
commit d77835d97b
No known key found for this signature in database
GPG Key ID: 2D2885533B869ED4
1 changed files with 37 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
README.md → README.org
View File

@ -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 <RET> 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 <RET> org-clock-waybar`.
#+end_src