From 1b72353dd5167127b2bb1a89414b8b01ea0d6b2b Mon Sep 17 00:00:00 2001
From: obarun <eric@obarun.org>
Date: Mon, 11 Dec 2023 17:39:23 +1100
Subject: [PATCH] improve execl-envfile doc and adapt other referring to it

---
 doc/execl-envfile.md | 50 +++++++++++++++++++++++++++++++++++++-------
 doc/frontend.md      |  9 ++++----
 doc/upgrade.md       | 13 ++++++++++--
 3 files changed, 58 insertions(+), 14 deletions(-)

diff --git a/doc/execl-envfile.md b/doc/execl-envfile.md
index 7213e2e6..c8479acf 100644
--- a/doc/execl-envfile.md
+++ b/doc/execl-envfile.md
@@ -45,11 +45,51 @@ This program expects to find a regular file or a directory in *src* containing o
 ## File syntax
 
 *src* is a text file or a directory containing lines of pairs with the syntax being: `key = value`
-Whitespace is permitted before and after *key*, and before or after *value*. Quoting is also possible.
+Whitespace is permitted before and after *key*, and before or after *value*.
 
-Empty lines or lines containing only whitespace are ignored. Lines beginning with `#` (also after whitespace) are ignored and typically used for comments. Comments are not possible at the end of lines: `key = value # comment` is not a valid comment.
+Empty lines, or lines containing only whitespace, are ignored. Lines beginning with `#` or `;` (possibly after some whitespace) are ignored (and typically used for comments). Leading and trailing whitespace is stripped from values; but a *value* can be double-quoted, which allows for inclusion of leading and trailing whitespace.
 
-If val begin by a `!` character: `key=!value` the key will be removed from the environment after the substitution.
+Escaping double-quoted can be done with backslash `\`. For instance,
+
+```
+cmd_args=-g \"daemon off;\"
+```
+
+C escapes, including hexadecimal and octal sequences, are supported in quoted values. Unicode codepoint sequences are not supported.
+
+If *value* is empty, *key* is still added to the environment, with an empty value.
+
+If you do not want *key* to be added to the environment at all, prefix the *value* with an exclamation mark `!`. Whitespace **are not permitted** between the `!` and `value`. For instance,
+
+```
+socket_name=!sname
+```
+
+In this case the *key* will be removed from the environment after the substitution.
+
+Variable name **must be** between `${}` to get it value. For instance, `$var` is not replaced by its value.
+
+Reusing the same variable or variable from the actual environment is allowed. In such case, variable name **must be** between `${}` to get it value. For instance, `$var` is not replaced by its value. For intance, an environment file can be declared
+
+```
+PATH=/usr/local/bin:${PATH}
+socket_name=sname
+socket_dir=dname
+socket=${socket_dir}/${socket_name}
+```
+
+The order of key-value pair declaration **doesn't matter**:
+
+```
+PATH=/usr/local/bin:${PATH}
+socket=${socket_dir}/${socket_name}
+socket_name=sname
+socket_dir=dname
+```
+
+### Limits
+
+*src* can not exceed more than `100` files. Each file can not contain more than `8191` bytes or more than `50` `key=value` pairs.
 
 ## Usage example
 
@@ -75,7 +115,3 @@ The equivalent with s6-envdir and importas would be:
 ```
 
 where `%%service_admconf%%` contains two named files `RUNDIR` and `CMD_ARGS` written with `/run/openntpd` and `-d -s` respectively.
-
-## Limits
-
-*src* can not exceed more than `100` files. Each file can not contain more than `8191` bytes or more than `50` `key=value` pairs.
diff --git a/doc/frontend.md b/doc/frontend.md
index 56df8649..25a3bb50 100644
--- a/doc/frontend.md
+++ b/doc/frontend.md
@@ -777,25 +777,24 @@ A file containing the `key=value` pair(s) will be created by default at `%%servi
         cmd_args=-d -s
     ````
 
-    The `!` character can be put in front of the value. **Do not** put space between the exclamation mark and the value.
+    The `!` character can precede the value. Ensure **no** space exists between the exclamation mark and the *value*. This action explicitly avoids setting the value of the *key* for the runtime process but only applies it at the start of the service. For example, the `key=value` pair passed to the following command line doesn't necessarily need to be included in the service's general environment variables
 
-    For example, the following is valid:
+    the following syntax is valid
 
     ````
         [environment]
         dir_run=!/run/openntpd
         cmd_args = !-d -s
     ````
-    where:
+    where this one is not
 
     ````
         [environment]
         dir_run=! /run/openntpd
         cmd_args = ! -d -s
     ````
-    is not.
 
-    This will explicitly **not** set the value of the key for the runtime process but only at the start of the service. In this example the `key=value` pair passed to the command line does not need to be present in the general environment variable of the service.
+    Refers to [execl-envfile](execl-envfile.html) for futhers information.
 
 ---
 
diff --git a/doc/upgrade.md b/doc/upgrade.md
index cb689f9e..d53d536a 100644
--- a/doc/upgrade.md
+++ b/doc/upgrade.md
@@ -40,16 +40,20 @@ The following field has been removed:
 
 - `@extdepends`: No longer necessary as services can depend on any service regardless of the tree used.
 
+Frontend files for regular account **must be** now localized at `%%service_system%%/user`, `%%service_adm%%/user` or `${HOME}/%%service_user%%`.
+
 ### Behavioral changes:
 
 - `@options`:
     - `pipeline`: This option was removed. It was only present for `s6-rc`.
+    - `env`: This option was removed. The simple declaration of the [environment] section.
 
 - `@shebang`: Deprecated but kept for compatibility reasons. Declare your shebang directly within the `@execute` field.
 
 - `@build`: Not mandatory anymore, as it will be declared 'auto' by default.
 Service Behavior
 
+- `@addservices`
 The `classic` type now accepts the fields `@depends` and `@requiredby`. The `classic` type replaces the `longrun` type.
 
 Logger destinations for `oneshot` type services can now be declared on a **tmpfs** directory, particularly useful during boot time.
@@ -60,11 +64,12 @@ The `bundle` and `longrun` types have been removed, replaced by `classic`, `ones
 
 ## [Environment] Section
 
-This section now allows reusing the same variable. For instance:
+This section now allows reusing the same variable or variable from the actual environment. For instance:
 
 ```
 socket_name=!/run/dbus/system_bus_socket
 cmd_args=!--system --address=unix:path=${socket_name}
+PATH=/usr/local/bin:${PATH}
 ```
 
 The order of key-value pair declaration **doesn't matter**:
@@ -74,13 +79,17 @@ cmd_args=!--system --address=unix:path=${socket_name}
 socket_name=!/run/dbus/system_bus_socket
 ```
 
+Variable name **must be** between `${}` to get it value. For instance, `$var` is not replaced by its value.
+
+Double-quote within *value* **must be** escaped with backslash `\`. Refers to the updated documentation of [execl-envfile](execl-envfile.html) for futhers information.
+
 ## Module Changes
 
 The `module` directory structure has been completely redesigned for better intuitiveness and comprehensiveness. Expect no compatibility with the previous version; a rewrite is required if you use `module` on your system.
 
 A `module` cannot contain another `module`; instead, you can declare it as a dependency via `@depends` or `@requiredby`. These can also be specified through the `configure` `module` script.
 
-Refer to the specific [module](module-creation.html) page for further information.
+Refer to the specific [module](module-creation.html) page for furthers information.
 
 ## Trees
 
-- 
GitLab