Improve documentation around the `include_dir` option.

Closes #1154. Thanks to Guzoft.

ChangeLog.txt

@@ -7,6 +7,7 @@ Broker:
   other security options. Closes #1149.
 - Fix include_dir not sorting config files before loading. This was partially
   fixed in 1.5 previously.
+- Improve documentation around the `include_dir` option. Closes #1154.
 
 Library:
 - Fix `mosquitto_topic_matches_sub()` not returning MOSQ_ERR_INVAL for

man/mosquitto.conf.5.xml

@@ -349,6 +349,51 @@
 						file. This option will only be processed from the main
 						configuration file. The directory specified must not
 						contain the main configuration file.</para>
+					<para>The configuration files in
+						<option>include_dir</option> are loaded in case
+						insensitive alphabetical order.</para>
+						<example title="Load Order for include_dir" label="Load Order for include_dir">
+							<para>Given the files
+								<replaceable>b.conf</replaceable>,
+								<replaceable>A.conf</replaceable>,
+								<replaceable>01.conf</replaceable>,
+								<replaceable>a.conf</replaceable>, and
+								<replaceable>00.conf</replaceable> inside
+								<option>include_dir</option>, the config files
+								would be loaded in this order:</para>
+						<programlisting language="config">
+00.conf
+01.conf
+A.conf
+a.conf
+b.conf
+</programlisting></example>
+					<para>If this option is used multiple times, then each
+						<option>include_dir</option> option is processed
+						completely in the order that they are written in the
+						main configuration file.</para>
+						<example title="Load Order for Multiple include_dir" label="Load Order for Multiple include_dir">
+							<para>Assuming a directory
+								<replaceable>one.d</replaceable> containing
+								files <replaceable>B.conf</replaceable> and
+								<replaceable>C.conf</replaceable>, and a second
+								directory <replaceable>two.d</replaceable>
+								containing files
+								<replaceable>A.conf</replaceable> and
+								<replaceable>D.conf</replaceable>, and a
+								config:</para>
+						<programlisting language="config">
+include_dir one.d
+include_dir two.d
+</programlisting><para>Then the config files would be loaded in this order:</para>
+						<programlisting language="config">
+# files from one.d
+B.conf
+C.conf
+# files from two.d
+A.conf
+D.conf
+</programlisting></example>
 				</listitem>
 			</varlistentry>
 			<varlistentry>

mosquitto.conf

@@ -872,6 +872,10 @@
 # in the main file. This option will only be processed from the main
 # configuration file. The directory specified must not contain the 
 # main configuration file.
+# Files within include_dir will be loaded sorted in case-insensitive
+# alphabetical order. If this option is given multiple times, all of the files
+# from the first instance will be processed before the next instance. See the
+# man page for examples.
 #include_dir
 
 # =================================================================