From 1a7092f545d9c2dba623dc4382bdc1284eecb2a3 Mon Sep 17 00:00:00 2001
From: Joachim Wiberg <troglobit@gmail.com>
Date: Wed, 10 Mar 2021 12:14:57 +0100
Subject: [PATCH] doc: update with new 'initctl cond set|clear foo' commands

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
---
 README.md         |  3 +++
 doc/conditions.md | 28 +++++++++++++++++++++++++++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 14439170..81a38ed3 100644
--- a/README.md
+++ b/README.md
@@ -356,6 +356,7 @@ Options:
   -b, --batch               Batch mode, no screen size probing
   -c, --create              Create missing paths (and files) as needed
   -f, --force               Ignore missing files and arguments, never prompt
+  -p, --plain               Use plain table headings, no ctrl chars
   -t, --no-heading          Skip table headings
   -v, --verbose             Verbose output
   -h, --help                This help text
@@ -375,6 +376,8 @@ Commands:
   disable  <CONF>           Disable  .conf in /etc/finit.d/enabled
   reload                    Reload  *.conf in /etc/finit.d (activate changes)
 
+  cond     set   <COND>     Set (assert) user-defined condition     +usr/COND
+  cond     clear <COND>     Clear (deassert) user-defined condition -usr/COND
   cond     show             Show condition status
   cond     dump             Dump all conditions and their status
 
diff --git a/doc/conditions.md b/doc/conditions.md
index 23df8f50..4da36b95 100644
--- a/doc/conditions.md
+++ b/doc/conditions.md
@@ -45,7 +45,31 @@ being created.
 Triggering
 ----------
 
-Conditions can only be triggered by built-in plugins.
+Conditions are mainly triggered (asserted) by built-in plugins, e.g.,
+`netlink.so` and `pidfile.so`, see below for built-in conditions.  Finit
+also supports user-defined conditions, sometimes referred to as static
+or one-shot conditions.  They live in the `<usr/...` namespace and are
+constrained to a flat hierarchy without any sub-directories, unlike the
+pidfile plugin, for instance.
+
+User-defined conditions are controlled using the `initctl cond set` and
+`initctl cond clear` commands:
+
+    initctl cond set foo
+    initctl cond clear foo
+
+The purpose of user-defined conditions is to be able to start or stop
+services, or run/task jobs, on external site-dependent stimuli.
+Example:
+
+    service [2345] <usr/foo> alarm --arg foo -- Foo alarm
+
+For convenience, prefixing with `usr/` is allowed, but any other slashes
+or period characters are disallowed.  E.g., to trigger the `Foo alarm`,
+the same as above, can also be achieved like this:
+
+    initctl cond set usr/foo
+    initctl cond clear usr/foo
 
 Conditions retain their current state until the next reconfiguration or
 runlevel change.  At that point all set conditions transition into the
@@ -57,6 +81,8 @@ unchanged) state of it.
 > **Note:** For `pid/` conditions it is expected that services "touch"
 >           or recreate their PID file on `SIGHUP`.
 
+Static (one-shot) conditions, like `usr/`, never enter the `flux` state.
+
 
 Built-in Conditions
 -------------------