From 94ade9ea192e514f3488bdeb8d1f51fdda2407c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=84min=20Baumeler?= <amin@indyfac.ch>
Date: Thu, 22 May 2025 12:39:54 +0200
Subject: [PATCH] First version of README

Minor improvements

Minor improvement

Minor improvement
---
 README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 fzf-vjour |  1 +
 2 files changed, 76 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 85c5835..f21c024 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,75 @@
-A `fzf`-based **journaling and notes** application with WebDav support.
+A [fzf](https://github.com/junegunn/fzf)-based **journaling and notes** application with CalDav support.
+
+Description and Use Case
+------------------------
+This application allows for a keyboard-controlled maneuvering of your notes and journal entries.
+A journal entry is nothing more than a note associated with a specific date.
+These entries are stored as [iCalendar](https://datatracker.ietf.org/doc/html/rfc5545) files of the type `VJOURNAL`.
+
+For instance, you could use this application as a minimalistic terminal-based counterpart of [jtx Board](https://jtx.techbee.at/) in a setup
+with a CalDav server, such as [Radicale](https://radicale.org/), and a synchronization tool like [vdirsyncer](http://vdirsyncer.pimutils.org/).
+
+Installation
+------------
+Just copy the file to your preferred location, e.g., `~/.local/bin`, and make it executable.
+
+### Requirements
+This is a POSIX script with inline `python3` elements.
+Make sure you have [fzf](https://github.com/junegunn/fzf), [batcat](https://github.com/sharkdp/bat), and [yq](https://github.com/mikefarah/yq) installed.
+For the `python3` code, we also require [icalendar](https://pypi.org/project/icalendar/).
+
+Configuration
+--------------
+This application is configured with a YAML file located at `$HOME/.config/fzf-vjour/config.yaml`.
+The entry `datadir` specifies the root directory of your journal and note entries.
+This directory may contain several subfolders, called _collections_.
+The entry `collections` is a list, where each item specifies a subfolder, given by `name`, and a label, given by `label` (any string).
+In the application, the user sees the collection labels instead of the collection names.
+This is particularly useful, because some servers use randomly generated names.
+Finally, a third entry `sync_cmd` specifies the command to be executed for synchronizing. 
+
+Consider the following example:
+```yaml
+datadir: ~/.journal
+sync_cmd: vdirsyncer sync journals
+collections:
+  - name: 12cacb18-d3e1-4ad4-a1d0-e5b209012e85
+    label: 💼
+  - name: 745ae7a0-d723-4cd8-80c4-75f52f5b7d90
+    label: 🏡
+```
+
+
+Here the files are stored in
+`~/.journal/12cacb18-d3e1-4ad4-a1d0-e5b209012e85` (work-related entries)
+and
+`~/.journal/745ae7a0-d723-4cd8-80c4-75f52f5b7d90` (personal collection).
+
+This configuration will work well with a `vdirsyncer` configuration such as 
+```confini
+[pair journals]
+a = "local"
+b = "remote"
+collections = ["from a", "from b"]
+
+[storage local]
+type = "filesystem"
+fileext = ".ics"
+path = "~/.journal"
+
+[storage remote]
+type = "caldav"
+item_types = ["VJOURNAL"]
+...
+```
+
+Usage
+-----
+Use the default `fzf` keys to navigate your notes. In addition, there are the following keybindings:
+| Key | Action |
+| --- | ------ |
+| enter | Open note/journal in your `$EDITOR` |
+| ctrl-d | Delete the seleted entry |
+| ctrl-n | Make a new entry |
+| ctrl-r | Refresh the view |
+| ctrl-s | Run the synchronization command |
diff --git a/fzf-vjour b/fzf-vjour
index ade0940..b8c085f 100755
--- a/fzf-vjour
+++ b/fzf-vjour
@@ -9,6 +9,7 @@ if [ ! -e "$CONFIGFILE" ]; then
   exit 1
 fi
 ROOT=$(yq '.datadir' <"$CONFIGFILE")
+ROOT=$(eval "echo $ROOT")
 if [ ! -d "$ROOT" ]; then
   echo "Root directory not set or wrongly set"
   exit 1