Improve documentation of persistent_client_expiration option.

Closes #2404. Thanks to Rainer Plischke.

ChangeLog.txt

@@ -9,6 +9,8 @@ Broker:
  MOSQ_EVT_MESSAGE event.
 - Fix unused flags in CONNECT command being forced to be 0, which is not
  required for MQTT v3.1. Closes #2522.
+- Improve documentation of `persistent_client_expiration` option.
+ Closes #2404.
 
 Client library:
 - Fix threads library detection on Windows under cmake. Bumps the minimum

man/mosquitto.conf.5.xml

@@ -842,15 +842,21 @@ log_timestamp_format %Y-%m-%dT%H:%M:%S
  <varlistentry>
  <term><option>persistent_client_expiration</option> <replaceable>duration</replaceable></term>
  <listitem>
- <para>This option allows persistent clients (those with
- clean session set to false) to be removed if they do
- not reconnect within a certain time frame. This is a
- non-standard option. As far as the MQTT spec is
- concerned, persistent clients persist forever.</para>
- <para>Badly designed clients may set clean session to false
- whilst using a randomly generated client id. This leads
- to persistent clients that will never reconnect. This
- option allows these clients to be removed.</para>
+ <para>
+ This option allows the session of persistent clients (those with clean
+ session set to false) <emphasis>that are not currently connected</emphasis> to be removed if they
+ do not reconnect within a certain time frame. This is a non-standard option
+ in MQTT v3.1. MQTT v3.1.1 and v5.0 allow brokers to remove client sessions.
+ </para>
+
+ <para>
+ Badly designed clients may set clean session to false whilst using a randomly
+ generated client id. This leads to persistent clients that connect once and
+ never reconnect. This option allows these clients to be removed. This option
+ allows persistent clients (those with clean session set to false) to be
+ removed if they do not reconnect within a certain time frame.
+ </para>
+
  <para>The expiration period should be an integer followed
  by one of h d w m y for hour, day, week, month and year
  respectively. For example:</para>

mosquitto.conf

@@ -141,14 +141,16 @@
 # accepted. MQTT imposes a maximum payload size of 268435455 bytes.
 #message_size_limit 0
 
-# This option allows persistent clients (those with clean session set to false)
-# to be removed if they do not reconnect within a certain time frame.
-#
-# This is a non-standard option in MQTT V3.1 but allowed in MQTT v3.1.1.
+# This option allows the session of persistent clients (those with clean
+# session set to false) that are not currently connected to be removed if they
+# do not reconnect within a certain time frame. This is a non-standard option
+# in MQTT v3.1. MQTT v3.1.1 and v5.0 allow brokers to remove client sessions.
 #
 # Badly designed clients may set clean session to false whilst using a randomly
-# generated client id. This leads to persistent clients that will never
-# reconnect. This option allows these clients to be removed.
+# generated client id. This leads to persistent clients that connect once and
+# never reconnect. This option allows these clients to be removed. This option
+# allows persistent clients (those with clean session set to false) to be
+# removed if they do not reconnect within a certain time frame.
 #
 # The expiration period should be an integer followed by one of h d w m y for
 # hour, day, week, month and year respectively. For example