Add --retain-handling to sub and rr clients

man/common/option-retain-handling.xml

@@ -0,0 +1,24 @@
+<varlistentry>
+	<term><option>--retain-handling</option> always | new | never</term>
+	<listitem>
+		<para>
+			Use this option to control the retain handling option when making a
+			subscription. This controls under what circumstances an existing
+			retained message is sent to the client when the subscription is
+			made.
+		</para>
+
+		<itemizedlist mark="circle">
+			<listitem><para><option>always</option> - always deliver retained messages</para></listitem>
+			<listitem><para>
+				<option>new</option> - deliver retained messages the first time
+				a subscription is made, but not on subsequent subscriptions. This
+				is useful for the case where you have a long running client using
+				a non-clean session. If the connection is dropped briefly, when the
+				client reconnects you will not receive the retained messages again.
+			</para></listitem>
+			<listitem><para><option>never</option> - never deliver retained messages</para></listitem>
+		</itemizedlist>
+	</listitem>
+</varlistentry>
+

man/mosquitto_rr.1.xml

@@ -76,6 +76,7 @@
 			<arg><option>-k</option> <replaceable>keepalive-time</replaceable></arg>
 			<arg><option>-q</option> <replaceable>message-QoS</replaceable></arg>
 			<arg><option>-V</option> <replaceable>protocol-version</replaceable></arg>
+			<arg><option>--retain-handling</option> always | new | never</arg>
 			<arg><option>-x</option> <replaceable>session-expiry-interval</replaceable></arg>
 			<sbr/>
 			<arg>
@@ -607,6 +608,7 @@
 						their display.</para>
 				</listitem>
 			</varlistentry>
+			<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-retain-handling.xml" />
 			<varlistentry>
 				<term><option>-S</option></term>
 				<listitem>

man/mosquitto_sub.1.xml

@@ -78,6 +78,7 @@
 			<arg><option>-k</option> <replaceable>keepalive-time</replaceable></arg>
 			<arg><option>-q</option> <replaceable>message-QoS</replaceable></arg>
 			<arg><option>--retain-as-published</option></arg>
+			<arg><option>--retain-handling</option> always | new | never</arg>
 			<arg><option>-V</option> <replaceable>protocol-version</replaceable></arg>
 			<arg><option>-x</option> <replaceable>session-expiry-interval</replaceable></arg>
 			<sbr/>
@@ -663,6 +664,7 @@ mosquitto_sub -t 'bbc/#' -T bbc/bbc1 --remove-retained</programlisting>
 						clients.</para>
 				</listitem>
 			</varlistentry>
+			<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="common/option-retain-handling.xml" />
 			<varlistentry>
 				<term><option>-S</option></term>
 				<listitem>