agendafs

A filesystem for your calendar.

commit ad9a15f657a08caea2c3183847021f6014540212
parent 16bca4d3c54de3d0b348cd99728142af286915b4
Author: Marc Coquand <marc@coquand.email>
Date:   Mon, 25 Aug 2025 13:00:19 +0200

Add docs with usage examples

Diffstat:
M
Makefile
 | 
3
+++
A
agendafs-examples.7.scd
 | 
103
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
M
agendafs.8.scd
 | 
7
++++---

3 files changed, 110 insertions(+), 3 deletions(-)
diff --git a/Makefile b/Makefile
@@ -22,6 +22,7 @@ clean:
 
 manpages:
 	scdoc < agendafs.8.scd > $(OUTDIR)/agendafs.8
+	scdoc < agendafs-examples.7.scd > $(OUTDIR)/agendafs-examples.7
 
 all: agendafs manpages
 
@@ -30,8 +31,10 @@ install:
 	install -m755 $(OUTDIR)/mount_agendafs.o $(DESTDIR)$(BINDIR)/mount.agendafs
 	install -m644 $(OUTDIR)/agendafs.8 $(DESTDIR)$(MANDIR)/man8/agendafs.8
 	ln -fs $(DESTDIR)$(MANDIR)/man8/agendafs.8 $(DESTDIR)$(MANDIR)/man8/mount.agendafs.8
+	install -m644 $(OUTDIR)/agendafs-examples.7 $(DESTDIR)$(MANDIR)/man7/agendafs-examples.7
 
 uninstall:
 	rm -f $(DESTDIR)$(BINDIR)/mount.agendafs
 	rm -r $(DESTDIR)$(MANDIR)/man8/mount.agendafs.8
 	rm -f $(DESTDIR)$(MANDIR)/man8/agendafs.8
+	rm -r $(DESTDIR)$(MANDIR)/man7/agendafs-examples.8
diff --git a/agendafs-examples.7.scd b/agendafs-examples.7.scd
@@ -0,0 +1,103 @@
+AGENDAFS-EXAMPLES(7)
+
+# NAME
+
+agendafs-examples - Ways to use agendafs
+
+# Description
+
+Agendafs can be combined with other tools to build your own *Personal
+Knowledge Management* system. With so much power at your hands, it can
+be hard to know what to do with it.
+
+Below are some inspiration to get you started.
+
+# Integrating with lf
+
+_lf_(1) is a a terminal file manager available on most UNIX systems. It
+works particularly well with agendafs.
+
+## Showing categories in the promptfmt.
+
+Categories are available from _getfattr_(1). The _lf_ prompt can be updated
+to display the current categories of the selected file with three lines of
+configuration added to lfrc.
+
+	```
+	cmd on-select &{{
+		lf -remote "send $id set promptfmt \"%d $(getfattr -n user.categories --only-values "$f")\""
+	}}
+	```
+
+## Showing class and status in the custom info
+
+The following script uses _awk_(1) to parse a directory of files and updates
+_lf_(1) to display a notification if a file is public and/or a draft
+
+	```
+	#!/usr/bin/sh
+	cd "$(dirname "$1")"
+
+	result=$(getfattr -d * | awk '
+	    /^# file: / {
+	        file = substr($0, 9);  
+	        is_private = 0;
+	        is_draft = 0;
+	    }
+	    
+	    /^user.class="private"/ {
+	        is_private = 1;
+	    }
+	 
+	    /^user.status="draft"/ {
+	        is_draft = 1;
+	    }
+
+	    END {
+	        for (f in files) {
+	            is_private = (files[f] ~ /user.class="private"/);
+	            is_draft = (files[f] ~ /user.status="draft"/);
+
+	            # Build the custom info string.
+	            info = "";
+	            if (is_private) {
+	                info = info "p,";
+	            }
+	            if (is_draft) {
+	                info = info "d,";
+	            }
+	            if (length(info) > 0) {
+	                info = substr(info, 1, length(info) - 1);
+	            }
+	            if (length(info) > 0) {
+	                printf "addcustominfo \"%s\" \"%s\"; ", f, info;
+	            }
+	        }
+	    }
+	    {
+	        if ($0 ~ /^# file: /) {
+	            file = substr($0, 9);
+	            files[file] = "";
+	        } else if (file != "") {
+	            files[file] = files[file] " " $0;
+	        }
+	    }
+	')
+
+	if [ -n "$result" ]; then
+	    lf -remote "send $id :$result"
+	fi
+	```
+
+Add the script to $PATH along with the following to your lfrc:
+
+	```
+	set info custom
+	cmd on-cd %{{
+		lf_show_status "$1"
+	}}
+	cmd on-init %{{
+		lf_show_status "$1"
+	}}
+	```
+
diff --git a/agendafs.8.scd b/agendafs.8.scd
@@ -116,9 +116,10 @@ _pimsync_(1)
 _mount.fuse_(8)
 _mount_(1)
 _fusermount_(1)
-_xattr(7)_
-_getfattr(1)_
-_setfattr(1)_
+_xattr_(7)
+_getfattr_(1)
+_setfattr_(1)
+_agendafs-examples_(7)
 
 vdirsyncer (https://vdirsyncer.pimutils.org/en/stabl)