README: multiple improvements

diff --git a/README.adoc b/README.adoc
index 7df94dc4e9da07577cb4f9ffee0a89c8a39be04e..f4a34feb91c2e259f25e2f3408e9fe6afb9659d4 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -17,12 +17,13 @@ It can also be read as "saf(e) configuration management" as it combines
 simplicity and safety in the following principles:
 
 - *fail fast*: catch (user) errors as soon as possible; host configuration
-  (including templates) evaluated locally to prevent partial configuration;
+  (including templates) is evaluated locally to prevent partial configuration;
   errors immediately abort the synchronization
-- *remote hosts untrusted*: clear security boundary between local and remote
-  host; data used from remote hosts is marked (detected groups); all output
-  from remote hosts is escaped to prevent terminal injection attacks; each
-  host only receives its configuration and no data from other hosts
+- *remote hosts are untrusted*: clear security boundary between local and
+  remote host; data used from remote hosts is marked tainted (detected
+  groups); all output from remote hosts is escaped to prevent terminal
+  injection attacks; each host only receives its own configuration and no data
+  from other hosts
 - *safety and security*: create files with "write to temporary file", "sync",
   "rename", "sync directory" for atomicity and durability; guard against
   symlink and other TOCTOU attacks; extensive test suite
@@ -43,32 +44,33 @@ contains the files, packages, services and commands which should be applied to
 all hosts which are members of this group.
 
 The configuration of all managed hosts is stored in a directory on the local
-host. Safcm uses https://yaml.org/[YAML] for all configuration files for its
-natural syntax. Strict type checks prevent potential pitfalls of more complex
-YAML syntax. Tasks like copying a file require no explicit configuration.
-
-Files consist of a tree of files (regular files and symbolic links) and
-directories with permissions, user/group and content. Files can use
-_templates_ for dynamic content depending on the host or its groups. Each path
-can have _trigger_ commands which are executed when the path itself or any
-sub-paths are modified during synchronization. Packages are package names of
-the remote operating system. Services are service names of the remote
-operating system. Commands are shell commands passed to `/bin/sh`.
-
-When files with the same path are present in multiple groups of a host an
+host. Safcm uses https://yaml.org/[YAML] for all configuration files. Strict
+type checks prevent potential pitfalls due to the complex YAML syntax. Tasks
+like copying a file require no explicit configuration.
+
+Files (regular files and symbolic links) and directories, including
+permissions, user/group and content are kept in a regular filesystem tree on
+the local host. Files can use _templates_ for dynamic content depending on the
+host or its groups. Each path can have _trigger_ commands which are executed
+when the path itself or any sub-paths are modified during synchronization.
+Packages are package names of the remote operating system. Services are
+service names of the remote operating system. Commands are shell commands
+passed to `/bin/sh`.
+
+When files with the same path are present in multiple groups of a host, an
 explicit _group order_ must be configured to resolve the conflict. Conflicts
 do not apply to packages and services which are simply merged from all groups.
 Commands are appended so that the same command can be executed multiple times.
 
-To sync the configuration to a remote host the local `safcm` binary connects
+To sync the configuration to a remote host, the local `safcm` binary connects
 to it via `ssh`. It then copies a _remote helper_ binary to `/tmp` on the
-remote host to later perform the actual sync. If the remote helper is already
-present, has the proper checksum, permissions and user/group then the copy is
-skipped. `safcm` then queries the remote host for information, including
-operating system, architecture and detected groups. With all relevant data
-collected it assigns the host its groups, evaluates the configuration
-including templates and finally sends it to the remote helper which then
-applies it to the remote host.
+remote host to perform the actual sync later. If the remote helper is already
+present, has the proper checksum, permissions and user/group then the copying
+step is skipped. `safcm` then queries the remote host for information,
+including operating system, architecture and detected groups. With all
+relevant data collected, it assigns the host to its groups, evaluates the
+configuration including templates and finally sends the new configuration to
+the remote helper which then applies it to the remote host.
 
 The synchronization happens in the following order which cannot be changed:
 
@@ -102,10 +104,10 @@ future, others are due to the design of safcm.
   `/root` which often have strict permissions by default, so carefully check
   the diff output for unwanted changes.
 
-- Full file content of all files is sent to the remote during synchronization.
-  This makes it impractical to synchronize large files with safcm. As most
-  configuration files are small this shouldn't be an issue for common
-  scenarios.
+- The full file content of all files is sent to the remote during
+  synchronization. This makes it impractical to synchronize large files with
+  safcm. Since most configuration files are small this shouldn't be an issue
+  for common scenarios.
 
 - Quoted strings in the output are quoted using Go's `%q` format string. The
   result is similar -- but not identical -- to quoted strings in regular shell
@@ -120,7 +122,7 @@ future, others are due to the design of safcm.
 
 == Requirements
 
-- build the `safcm` binary and remote helper:
+- to build the `safcm` binary and remote helper:
   * Go >= 1.16
   * GNU make