man,doc: document some aspects of user record management/homed a bit better

Fixes: #29759
(cherry picked from commit 7480859)
(cherry picked from commit 912fb76)
(cherry picked from commit 318c3af)

Author: poettering

docs/USER_RECORD.md

@@ -701,28 +701,40 @@ for other purposes too.
 
 The `perMachine` field in the top-level object is an array of objects. When
 processing the user record first the various fields on the top-level object
-should be used. Then this array should be iterated in order, and the various
-settings be applied that match either the indicated machine ID or host
-name. There may be multiple array entries that match a specific system, in
-which case all the object's setting should be applied. If the same option is
-set in the top-level object as in a per-machine object the latter wins and
-entirely undoes the setting in the top-level object (i.e. no merging of
-properties that are arrays themselves is done). If the same option is set in
-multiple per-machine objects the one specified later in the array wins (and
-here too no merging of individual fields is done, the later field always wins
-in full).
+should be parsed. Then, the `perMachine` array should be iterated in order, and
+the various settings within each contained object should be applied that match
+either the indicated machine ID or host name, overriding any corresponding
+settings previously parsed from the top-level object. There may be multiple
+array entries that match a specific system, in which case all settings should
+be applied. If the same option is set in the top-level object as in a
+per-machine object then the per-machine setting wins and entirely undoes the
+setting in the top-level object (i.e. no merging of properties that are arrays
+is done). If the same option is set in multiple per-machine objects the one
+specified later in the array wins (and here too no merging of individual fields
+is done, the later field always wins in full). To summarize, the order of
+application is (last one wins):
+
+1. Settings in the top-level object
+2. Settings in the first matching `perMachine` array entry
+3. Settings in the second matching `perMachine` array entry
+4. …
+5. Settings in the last matching `perMachine` array entry
 
 The following fields are defined in this section:
 
 `matchMachineId` → An array of strings that are formatted 128bit IDs in
 hex. If any of the specified IDs match the system's local machine ID
-(i.e. matches `/etc/machine-id`) the fields in this object are honored.
+(i.e. matches `/etc/machine-id`) the fields in this object are honored. (As a
+special case, if only a single machine ID is listed this field may be a single
+string rather than an array of strings.)
 
-`matchHostname` → An array of strings that are valid hostnames. If any of
-the specified hostnames match the system's local hostname, the fields in this
+`matchHostname` → An array of strings that are valid hostnames. If any of the
+specified hostnames match the system's local hostname, the fields in this
 object are honored. If both `matchHostname` and `matchMachineId` are used
 within the same array entry, the object is honored when either match succeeds,
-i.e. the two match types are combined in OR, not in AND.
+i.e. the two match types are combined in OR, not in AND. (As a special case, if
+only a single machine ID is listed this field may be a single string rather
+than an array of strings.)
 
 These two are the only two fields specific to this section. All other fields
 that may be used in this section are identical to the equally named ones in the

man/org.freedesktop.home1.xml

@@ -305,9 +305,14 @@ node /org/freedesktop/home1 {
       user record with the new passwords/authentication token data is specified as empty the existing user
       record's settings are propagated down to the home directory storage. This is typically used after a
       user record is updated using <function>UpdateHome()</function> in order to propagate the
-      secrets/authentication tokens down to the storage. This method is equivalent to
-      <function>ChangePassword()</function> on the <classname>org.freedesktop.home1.Home</classname>
-      interface.</para>
+      secrets/authentication tokens down to the storage. Background: depending on the backend the user's
+      authentication credentials are stored at multiple places: the user record kept on the host, the user
+      record kept in the home directory and the encrypted LUKS volume slot. If the home directory is used on
+      a different machined temporarily, and the password is changed there, and then is moved back to the
+      original host, the passwords of the three might get out of sync. By issuing
+      <function>ChangePasswordHome()</function> the three locations are updated to match the newest
+      information. This method is equivalent to <function>ChangePassword()</function> on the
+      <classname>org.freedesktop.home1.Home</classname> interface.</para>
 
       <para><function>LockHome()</function> temporarily suspends access to a home directory, flushing out any
       cryptographic keys from memory. This is only supported on some back-ends, and usually done during system