agendafs

A filesystem for your calendar.

git clone git://mccd.space/agendafs
commit 6a3c8597b4e4666ac1c479782de5d7cffe10fd41
parent f364188230c71eb72a1453ad9792bd4f8df3cc54
Author: Marc Coquand <marc@coquand.email>
Date:   Mon,  2 Jun 2025 12:00:16 +0100

Update readme

Diffstat:

MREADME.md | 113++++++++++++++++++++++++++++++++++++-------------------------------------------


1 file changed, 52 insertions(+), 61 deletions(-)
diff --git a/README.md b/README.md
@@ -1,6 +1,36 @@
-# caldavfs - Mount your caldav server as a filesystem
+# caldavfs 
 
-`caldavfs` is a FUSE-based filesystem written in C. Use it to manage your journal, todos, events et.c. as plain-text files that are easy to modify.
+`caldavfs` is a FUSE-based filesystem written in C that works with [vdirsyncer](https://vdirsyncer.pimutils.org/).
+
+To use it:
+
+```
+$ export CALDAVFS_ICS_DIR='~/.journals/the-journal'
+$ mount_caldavfs /tmp/local-journal
+```
+
+Now your `.ics` files are available as plain-text files:
+
+```
+$ cat /tmp/local-journal/19970901-13:00.txt
+Staff meeting minutes
+---
+1. Staff meeting: Participants include Joe, Lisa and Bob. Aurora project plans were reviewed. There is currently no budget reserves for this project. Lisa will escalate to management. Next meeting on Tuesday.
+2. Telephone Conference: ABC Corp. sales representative called to discuss new printer. Promised to get us a demo by Friday.
+3. Henry Miller (Handsoff Insurance): Car was totaled by tree. Is looking into a loaner car. 654-2323 (tel).
+```
+
+Edit with your favorite editor and sync
+
+```
+$ $EDITOR /tmp/local-journal/19970901-13:00.txt
+$ # when done
+vdirsyncer sync
+```
+
+## Status
+
+POC stage, still very early alpha.
 
 ## Motivation
 
@@ -25,36 +55,15 @@ spec, VJOURNAL entries look like this:
   END:VJOURNAL
 ```
 
-These are not really intended to be edited by users. Using `caldavfs`,
-you can mount a directory of `.ics` files. Once mounted, it will expose the
-entries in a way that is more human-readable:
-
-1997-09-01-13:00.txt
-```
-Staff meeting minutes
----
-1. Staff meeting: Participants include Joe, Lisa and Bob. Aurora project plans were reviewed. There is currently no budget reserves for this project. Lisa will escalate to management. Next meeting on Tuesday.
-2. Telephone Conference: ABC Corp. sales representative called to discuss new printer. Promised to get us a demo by Friday.
-3. Henry Miller (Handsoff Insurance): Car was totaled by tree. Is looking into a loaner car. 654-2323 (tel).
-```
-
-Now you can open the files in your favorite editor and any changes you make
-will be reflected in the original journal. Use your favorite tools: grep, vim, ls et.c.
-
+These are not really intended to be edited by users.
 
 ## Dependencies
 
-Right now it's built with GCC, but the aim is for it using only [cproc](https://sr.ht/~mcf/cproc/). You'll also need libfuse and pkg-config.
+Some C compiler along with libfuse and pkg-config.
 
 Right now you also need a tool that syncs .ics files with a caldav server,
 like [vdirsyncer](https://vdirsyncer.pimutils.org/en/stable/when.html#).
 
-Someday I hope that `caldavfs` handles it.
-
-## Why C?
-
-I started this project to improve my C skills.
-
 ## Building
 
 Run
@@ -68,30 +77,26 @@ make
 Note: This is still in early alpha. It will change, break and more. Don't
 use it for any critical data.
 
-To make testing safer, create a dedicated calendar for just your journal
-files in your caldav server.
+1. Set up a new calendar with VJOURNAL support. See below for how its done in Nextcloud.
 
-Then set up [vdirsyncer](https://vdirsyncer.pimutils.org/en/stable/installation.html).
+2. Set up [vdirsyncer](https://vdirsyncer.pimutils.org/en/stable/installation.html).
 
-Once setup, you will have a directory of all your calendars. Locate the one that you are going to use for journals.
-
-Now, set the `CALDAVFS_ICS_DIR` variable and run:
+3. You will now have a directory of all your calendars. Locate the one that you are going to use for journals.
 
 ```
-mkdir /tmp/journal
-export CALDAVFS_ICS_DIR=~/.calendars/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/
-# -d -f to launch in debug mode, see libfuse for more options
-mount_caldavfs -d -f /tmp/journal
-# Or if you are for some reason not using rc-shell, replace
-# `{date +'...'} with $(date +'...')
-new_file=/tmp/journal/`{date +'%Y%m%d-%H:%M.txt'}
-touch $new_file
-$EDITOR $new_file
+$ mkdir /tmp/journal
+$ export CALDAVFS_ICS_DIR=~/.calendars/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/
+$ # -d -f to launch in debug mode, see libfuse for more options
+$ mount_caldavfs -d -f /tmp/journal
+$ # Or if you are for some reason not using plan9 rc, replace
+$ # `{date +'...'} with $(date +'...')
+$ new_file=/tmp/journal/`{date +'%Y%m%d-%H:%M.txt'}
+$ touch $new_file
+$ $EDITOR $new_file
 ```
 
-The last part can be moved to a separate file.
 
-### VJOURNAL support
+### VJOURNAL support in Caldav
 
 To have vjournal support on Nextcloud, I needed to create the calendar manually...
 
@@ -134,14 +139,11 @@ Longer text
 The `---` are mandatory.
 
 
-## Status
-
-POC stage, still very early alpha.
-
-Planned features:
+## Planned features
 - [ ] VJOURNAL - Now the first true journaling filesystem!
 	- [x] Create
-	- [x] Delete
+	- [x] Delete locally
+	- [ ] Delete remote
 	- [x] Read
 	- [x] Rename
 	- [x] Write
@@ -154,18 +156,7 @@ Planned features:
 - [ ] VALARM
 - [ ] VFREEBUSY
 
-## Setup
-
-caldavfs works together with [vdirsyncer](https://vdirsyncer.pimutils.org/en/stable/when.html#). Vdirsyncer is used to periodically sync `.ics` files to your caldav server, allowing you to have an offline copy.
 
-In the future I might build the vdirsyncer functionality into this. But for now you will need it for this to work.
-
-
-## Usage
+## Why C?
 
-```
-mkdir /tmp/journal
-./journalfs $HOME/.journal/XXX-XXX-XXX /tmp/journal
-# Add -d for debugging
-```
-Will mount journalfs
+I started this project to improve my C skills.