From 975fb8992ef7255f1570d0ef6a926ac5101023e1 Mon Sep 17 00:00:00 2001
From: Tom Eastep <teastep@shorewall.net>
Date: Wed, 9 Jan 2013 08:00:59 -0800
Subject: [PATCH] Add warnings about line continuation vs. comments

Signed-off-by: Tom Eastep <teastep@shorewall.net>
---
 docs/configuration_file_basics.xml | 32 +++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/docs/configuration_file_basics.xml b/docs/configuration_file_basics.xml
index dfef73b20..fc70b3f45 100644
--- a/docs/configuration_file_basics.xml
+++ b/docs/configuration_file_basics.xml
@@ -142,10 +142,16 @@
         </listitem>
 
         <listitem>
-          <para><filename>/etc/shorewall/blacklist</filename> - lists
+          <para><filename>/etc/shorewall/blacklist</filename> - Deprecated in
+          favor of <filename>/etc/shorewall/blrules</filename>. Lists
           blacklisted IP/subnet/MAC addresses.</para>
         </listitem>
 
+        <listitem>
+          <para><filename>/etc/shorewall/blrules</filename> — Added in
+          Shorewall 4.5.0. Define blacklisting and whitelisting.</para>
+        </listitem>
+
         <listitem>
           <para><filename>/etc/shorewall/init</filename> - commands that you
           wish to execute at the beginning of a <quote>shorewall start</quote>
@@ -258,6 +264,11 @@
           start/restart when LOAD_HELPERS_ONLY=Yes in
           <filename>shorewall.conf</filename>.</para>
         </listitem>
+
+        <listitem>
+          <para><filename>/usr/share/arprules</filename> — Added in Shorewall
+          4.5.12. Allows specification of arptables rules.</para>
+        </listitem>
       </itemizedlist></para>
 
     <para><emphasis role="bold">If you need to change a file in
@@ -297,6 +308,12 @@
       <programlisting># This is a comment
 ACCEPT  net     $FW      tcp     www     #This is an end-of-line comment</programlisting>
     </example>
+
+    <important>
+      <para>If a comment ends with a backslash ("\"), the next line will also
+      be treated as a comment. See <link linkend="Continuation">Line
+      Continuation</link> below.</para>
+    </important>
   </section>
 
   <section id="Names">
@@ -516,6 +533,19 @@ ACCEPT      net:\
       continuation line does not end with a comma or colon, the leading white
       space in the last line is not ignored.</para>
     </example>
+
+    <important>
+      <para>A trailing backslash is not ignored in a comment. So the continued
+      rule above can be commented out with a single '#' as follows:</para>
+
+      <programlisting>#ACTION     SOURCE          DEST            PROTO           DEST
+#                                                           PORT(S)
+<emphasis role="bold">#</emphasis>ACCEPT     net:\
+            206.124.146.177,\
+            206.124.146.178,\
+            206.124.146.180\
+                            dmz             tcp             873</programlisting>
+    </important>
   </section>
 
   <section id="Pairs">