Update documentation

Signed-off-by: Tom Eastep <teastep@shorewall.net>

Shorewall/manpages/shorewall-conntrack.xml

@@ -54,7 +54,7 @@
     <replaceable>format</replaceable>.</para>
 
     <simplelist>
-      <member><emphasis role="bold">FORMAT</emphasis>
+      <member><emphasis role="bold">[?]FORMAT</emphasis>
       <replaceable>format</replaceable></member>
     </simplelist>
 
@@ -62,7 +62,9 @@
     role="bold">1</emphasis>,<emphasis role="bold">2</emphasis> or <emphasis
     role="bold">3</emphasis>.</para>
 
-    <para>Format 3 was introduced in Shorewall 4.5.10.</para>
+    <para>Format 3 was introduced in Shorewall 4.5.10. The optional '?' was
+    introduced in Shorewall 4.5.11 and ?FORMAT is the preferred form; the form
+    without the '?' is deprecated.</para>
 
     <para>Comments may be attached to Netfilter rules generated from entries
     in this file through the use of COMMENT lines. These lines begin with the

Shorewall/manpages/shorewall-interfaces.xml

@@ -52,9 +52,12 @@
     <para>The format is specified by a line as follows:</para>
 
     <blockquote>
-      <para><emphasis role="bold">FORMAT {1|2}</emphasis></para>
+      <para><emphasis role="bold">[?]FORMAT {1|2}</emphasis></para>
     </blockquote>
 
+    <para>The optional '?' was introduced in Shorewall 4.5.11 and ?FORMAT is
+    the preferred form; the form without the '?' is deprecated.</para>
+
     <para>The columns in the file are as follows.</para>
 
     <variablelist>
@@ -652,7 +655,7 @@ loc     eth2            -</programlisting>
 
             <varlistentry>
               <term><emphasis
-	      role="bold">sfilter=(<emphasis>net</emphasis>[,...])</emphasis></term>
+              role="bold">sfilter=(<emphasis>net</emphasis>[,...])</emphasis></term>
 
               <listitem>
                 <para>Added in Shorewall 4.4.20. This option provides an

Shorewall/manpages/shorewall-tcrules.xml

@@ -63,9 +63,12 @@
     <para>The format is specified by a line as follows:</para>
 
     <blockquote>
-      <para><emphasis role="bold">FORMAT {1|2}</emphasis></para>
+      <para><emphasis role="bold">[?]FORMAT {1|2}</emphasis></para>
     </blockquote>
 
+    <para>The optional '?' was introduced in Shorewall 4.5.11 and ?FORMAT is
+    the preferred form; the form without the '?' is deprecated.</para>
+
     <para>The columns in the file are as follows (where the column name is
     followed by a different name in parentheses, the different name is used in
     the alternate specification syntax).</para>

Shorewall6/manpages/shorewall6-conntrack.xml

@@ -54,7 +54,7 @@
     <replaceable>format</replaceable>.</para>
 
     <simplelist>
-      <member><emphasis role="bold">FORMAT</emphasis>
+      <member><emphasis role="bold">[?]FORMAT</emphasis>
       <replaceable>format</replaceable></member>
     </simplelist>
 
@@ -62,7 +62,9 @@
     role="bold">1</emphasis>,<emphasis role="bold">2</emphasis> or <emphasis
     role="bold">3</emphasis>.</para>
 
-    <para>Format 3 was introduced in Shorewall 4.5.10.</para>
+    <para>Format 3 was introduced in Shorewall 4.5.10. The optional '?' was
+    introduced in Shorewall 4.5.11 and ?FORMAT is the preferred form; the form
+    without the '?' is deprecated.</para>
 
     <para>Comments may be attached to Netfilter rules generated from entries
     in this file through the use of COMMENT lines. These lines begin with the

Shorewall6/manpages/shorewall6-interfaces.xml

@@ -52,9 +52,12 @@
     <para>The format is specified by a line as follows:</para>
 
     <blockquote>
-      <para><emphasis role="bold">FORMAT {1|2}</emphasis></para>
+      <para><emphasis role="bold">[?]FORMAT {1|2}</emphasis></para>
     </blockquote>
 
+    <para>The optional '?' was introduced in Shorewall 4.5.11 and ?FORMAT is
+    the preferred form; the form without the '?' is deprecated.</para>
+
     <para>The columns in the file are as follows.</para>
 
     <variablelist>
@@ -412,7 +415,7 @@ loc     eth2            -</programlisting>
 
             <varlistentry>
               <term><emphasis
-	      role="bold">sfilter=(<emphasis>net</emphasis>[,...])</emphasis></term>
+              role="bold">sfilter=(<emphasis>net</emphasis>[,...])</emphasis></term>
 
               <listitem>
                 <para>Added in Shorewall 4.4.20. At this writing (spring

Shorewall6/manpages/shorewall6-tcrules.xml

@@ -63,9 +63,12 @@
     <para>The format is specified by a line as follows:</para>
 
     <blockquote>
-      <para><emphasis role="bold">FORMAT {1|2}</emphasis></para>
+      <para><emphasis role="bold">[?]FORMAT {1|2}</emphasis></para>
     </blockquote>
 
+    <para>The optional '?' was introduced in Shorewall 4.5.11 and ?FORMAT is
+    the preferred form; the form without the '?' is deprecated.</para>
+
     <para>The columns in the file are as follows (where the column name is
     followed by a different name in parentheses, the different name is used in
     the alternate specification syntax).</para>

docs/Actions.xml

@@ -350,6 +350,11 @@ ACCEPT   -              -               tcp     135,139,445
 
       <programlisting>FORMAT 2</programlisting>
 
+      <para>Beginning with Shorewall 4.5.11, the preferred format is as shown
+      below, and the above format is deprecated.</para>
+
+      <programlisting>?FORMAT 2</programlisting>
+
       <para>When using Shorewall 4.4.16 or later, there are no restrictions
       regarding which targets can be used within your action.</para>
 

docs/Macros.xml

@@ -286,6 +286,11 @@ ACCEPT           fw       loc             tcp      135,139,445</programlisting>
 
       <programlisting>FORMAT 2</programlisting>
 
+      <para>Beginning with Shorewall 4.5.11, the preferred format is as shown
+      below, and the above format is deprecated.</para>
+
+      <programlisting>?FORMAT 2</programlisting>
+
       <para>There are no restrictions regarding the ACTIONs that can be
       performed in a macro.</para>
 

docs/configuration_file_basics.xml

@@ -1086,6 +1086,75 @@ SHELL cat /etc/shorewall/rules.d/*.rules 2&gt; /dev/null || true</programlisting
     </example>
   </section>
 
+  <section>
+    <title>?FORMAT Directive</title>
+
+    <para>A number of different files support multiple formats. Prior to
+    Shorewall 4.5.11, the format was specified by a line having 'FORMAT' as
+    the first token. This requires each of the file processors to handle
+    FORMAT separately.</para>
+
+    <para>In Shorewall 4.5.11, the ?FORMAT Directive was created to centralize
+    processing of FORMAT directives. The old entries, while still supported,
+    are now deprecated.</para>
+
+    <para>The format directive is as follows:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>?FORMAT <replaceable>format</replaceable></term>
+
+        <listitem>
+          <para>Where format is an integer. In all cases, the default format
+          is 1. The following table shows the files that have different
+          formats and the supported formats for each.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <informaltable>
+      <tgroup align="left" cols="2">
+        <tbody>
+          <row>
+            <entry>FILE</entry>
+
+            <entry>FORMATS</entry>
+          </row>
+
+          <row>
+            <entry>action files (action.*)</entry>
+
+            <entry>1 and 2</entry>
+          </row>
+
+          <row>
+            <entry>conntrack</entry>
+
+            <entry>1, 2 and 3</entry>
+          </row>
+
+          <row>
+            <entry>interfaces</entry>
+
+            <entry>1 and 2</entry>
+          </row>
+
+          <row>
+            <entry>macro files (macro.*)</entry>
+
+            <entry>1 and 2</entry>
+          </row>
+
+          <row>
+            <entry>tcrules</entry>
+
+            <entry>1 and 2</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+  </section>
+
   <section id="CONFIG_PATH">
     <title>CONFIG_PATH</title>