From 2f1caebaae99914d9dd04118ac5f82c15dd2958c Mon Sep 17 00:00:00 2001
From: Xavier Del Campo Romero <xavi.dcr@tutanota.com>
Date: Sat, 22 Jul 2023 04:14:41 +0200
Subject: [PATCH] README.md: Update according to thumbnail generation

---
 README.md           | 33 +++++++++++++++++++++--
 thumbnail/README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 97 insertions(+), 2 deletions(-)
 create mode 100644 thumbnail/README.md

diff --git a/README.md b/README.md
index 3138817..0cc41f5 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,9 @@ portability, minimalism, simplicity and efficiency.
 - Uses [`libweb`](https://gitea.privatedns.org/xavi/libweb), a tiny web framework.
 - A simple JSON file as the credentials database.
 - No JavaScript.
+- Thumbnail generation can be optionally provided via a
+[separate application](thumbnail/README-md) and enabled by `slcl` via a command
+line option. Inter-process communication is achieved via a named pipe.
 
 ### TLS
 
@@ -123,16 +126,32 @@ anything users put into them.
 
 **Note:** `slcl` creates the given directory if it does not exist.
 
+[Generated thumbnails](thumbnail/README.md) are stored into another directory,
+namely `thumbnails`, which is automatically created with directory mode bits
+set to `0700`.
+
+```
+.
+├── db.json
+├── public
+├── thumbnails
+└── user
+```
+
 A more complete example:
 
 ```
 .
 ├── db.json
 ├── public
-│   └── 44e03ab1bc3b0eff1567c76619186596 -> user/alice/file.txt
+│   └── 44e03ab1bc3b0eff1567c76619186596 -> user/alice/file.jpg
+├── thumbnails
+│   ├── alice
+│   │   └── file.jpg
+│   └── john
 └── user
     ├── alice
-    │   └── file.txt
+    │   └── file.jpg
     └── john
         └── file2.txt
 ```
@@ -199,6 +218,16 @@ temporary directory to the database, which might be an expensive operation.
 Therefore, in order to avoid expensive copies, define a custom temporary
 directory that resides on the same filesystem.
 
+#### Thumbnail generation and rendering
+
+Optionally, `slcl` displays thumbnails when listing a directory, if available
+from the `thumbnails/` directory. In order to update these thumbnails when
+files are added/removed to/from the database, a separate application must be
+executed. See its [`README.md`](thumbnail/README.md) for further reference.
+
+`slcl` provides the `-F` command line option to enable the use of a named pipe
+that shall be used by the [thumbnail generation tool](thumbnail/).
+
 ## Why this project?
 
 Previously, I had been recommended Nextcloud as an alternative to proprietary
diff --git a/thumbnail/README.md b/thumbnail/README.md
new file mode 100644
index 0000000..5bd876a
--- /dev/null
+++ b/thumbnail/README.md
@@ -0,0 +1,66 @@
+# Thumbnail generation tool for `slcl`
+
+This directory defines a separation application to be used in conjunction with
+`slcl`, aimed to update the thumbnail database automatically whenever files
+are added/removed to/from the database.
+
+### Root permissions
+
+This application requires no `root` permissions. So, in order to avoid the
+risk for security bugs, **please do not run this application as `root`**.
+
+## Requirements
+
+- A POSIX environment.
+- [`dynstr`](https://gitea.privatedns.org/xavi92/dynstr)
+(provided as a `git` submodule).
+- MagickCore
+- CMake (optional).
+
+### Ubuntu / Debian
+
+#### Mandatory packages
+
+```sh
+sudo apt install build-essential libmagickcore-6.q16-dev
+```
+
+#### Optional packages
+
+```sh
+sudo apt install cmake
+```
+
+## How to use
+### Build
+
+Similarly to `slcl`, two build environments are provided - feel free to choose
+any of them:
+
+- A mostly POSIX-compliant [`Makefile`](Makefile).
+- A [`CMakeLists.txt`](CMakeLists.txt).
+
+`thumbnail` can be built using the standard build process:
+
+#### Make
+
+```sh
+$ make
+```
+
+#### CMake
+
+```sh
+$ mkdir build/
+$ cmake ..
+$ cmake --build .
+```
+
+## Usage
+
+This tool only consumes one argument: the directory containing the instance
+database, which must be the same used by `slcl`. For example:
+
+```sh
+thumbnail ~/my-db
+```