From aff4272baa6eab1852c8991ddfcae83036a72cbc Mon Sep 17 00:00:00 2001
From: Philippe Pittoli <karchnu@karchnu.fr>
Date: Sat, 4 Feb 2023 03:44:32 +0100
Subject: [PATCH] README: add some explanations.

---
 README.md | 67 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 49 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index f94dea2..4f687a8 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,58 @@
-# USAGE
+# What
 
-As all programs from `Baguette` repositories, a `-h` option is available for the program.
+`mailer` is an application to send templated emails.
+Templates are in the [Crinja format][crinja] (a Jinja derivative).
 
 ```Bash
+# Get some help.
 mailer -h
 ```
 
-### Sending a mail
+# Sending a mail
 
 ```Bash
-# One-shot email transfer.
+# One-shot email transfer. "login" and "token" are template parameters.
 # mailer send <template> <email>
-login=mypseudo token=aabbccdd  mailer send activation-email test@example.com
+FROM=no-reply@example.com \
+	SUBJECT="Activate your email" \
+	login=mypseudo \
+	token=aabbccdd \
+	mailer send activation-email user@home.com
 ```
 
-### Configuration
+By default, configuration is:
 
-As all programs from `Baguette` repositories, a configuration file either in the `$XDG_CONFIG_HOME/baguette/` (first guess) or in the `/etc/baguette/` directory can be used.
+- smtp deamon host is '127.0.0.1', port 25
+- template directory is `/etc/mailer/templates/`
+- FROM and SUBJECT (mail object) are retrieved from environment variables
 
-Here an exhaustive example:
+So, in the previous example, without any configuration, the template *activation-email* refers to the file `/etc/mailer/templates/activation-email.j2` (the `j2` extension is for Jinja).
+
+The `/etc/mailer/templates/activation-email.j2` template could look like this:
+```
+Hello and welcome to example.com!
+
+To activate your account, please follow the link bellow:
+  https://example.com/user-activation/{{ login }}/{{ token }}
+
+Thanks for trusting us!
+Have a good day,
+-- 
+Staff of example.com.
+```
+
+# Configuration
+
+As most programs from `Baguette` repositories, a configuration file can be used.
+The configuration file should be either in `$XDG_CONFIG_HOME/baguette/` (first guess) or in `/etc/baguette/`.
+
+In `mailer`, this file is used to configure:
+
+- how to contact the smtp deamon (host and port)
+- what directory should be used for templates
+- *FROM* and *SUBJECT* email fields
+
+An exhaustive example:
 
 ```YAML
 # ~/.config/baguette/mailer.yml
@@ -27,24 +61,21 @@ Here an exhaustive example:
 smtpd_host: localhost
 smtpd_port: 25
 
-# Where to find templates, if not in the defaut directory (/etc/baguette/mailer/templates/).
-templates_directory: /path/to/mailer/templates
+# Where to find templates, if not in the defaut directory (/etc/mailer/templates/).
+templates_directory: /etc/mailer/templates
 
 # Configuration for each template.
 templates:
     # Template name, associated to the mail configuration: "from" and "subject" headers.
-    mail-activation-fr:
+    # Template names match the template file name in the template directory.
+    # In this example, the following template file is:
+    # /etc/mailer/templates/example.com-mail-activation-en.j2
+    example.com-mail-activation-en:
         from: no-reply@example.com
         subject: Account activation on the example.com website
-    mail-recovery-fr:
+    example.com-mail-recovery-en:
         from: no-reply@example.com
         subject: Mail recovery for the example.com website
 ```
 
-### Templates
-
-Templates:
-- are in the [Crinja format][crinja] (a Jinja derivative)
-- located by default in `/etc/baguette/mailer/templates`
-
 [crinja]: https://github.com/straight-shoota/crinja