Improve documentation

The Include and Define options, the ordering in config options, etc.

README.md

@@ -407,8 +407,8 @@ You can append an asterisk `*` to the site field of filtering rules for
 substring matching. Otherwise, the filter searches for an exact match with the 
 site field in the rule.
 
-The order of filtering rules is important. The order of from, to, and log 
-parts is not important. The order of log actions is not important.
+The ordering of filtering rules is important. The ordering of from, to, and 
+log parts is not important. The ordering of log actions is not important.
 
 If the UserAuth option is disabled, only client IP addresses can be used in 
 the from part of filtering rules.

src/sslproxy.1

@@ -421,8 +421,8 @@ You can append an asterisk * to the site field of filtering rules for
 substring matching. Otherwise, the filter searches for an exact match with the 
 site field in the rule.
 .LP
-The order of filtering rules is important. The order of from, to, and log 
-parts is not important. The order of log actions is not important.
+The ordering of filtering rules is important. The ordering of from, to, and 
+log parts is not important. The ordering of log actions is not important.
 .LP
 If the UserAuth option is disabled, only client IP addresses can be used in 
 the from part of filtering rules.
@@ -526,7 +526,10 @@ NAT ENGINES for a list of NAT engines currently supported by SSLproxy.
 .TP
 .B \-f \fIconffile\fP
 Read configuration from \fIconffile\fP. Configuration files can use the 
-Include option for loading configuration from an include file too.
+Include option for loading configuration from an include file too. Note that 
+the ordering of options, rules, and proxyspecs in configuration files (and on 
+the command line) is important. For example, rules and proxyspecs can only 
+make use of the options defined earlier.
 .TP
 .B \-F \fIlogspec\fP
 Log connection content to separate log files with the given path specification

src/sslproxy.conf

@@ -2,6 +2,10 @@
 #
 # Use the -f command line option to start sslproxy with a config file.
 # See sslproxy.conf(5) and sslproxy(1) for documentation.
+#
+# Note that the ordering of options, rules, and proxyspecs in configuration 
+# files (and on the command line) is important. For example, rules and 
+# proxyspecs can only make use of the options defined earlier.
 
 # Use CA cert (and key) to sign forged certs.
 # Equivalent to -c command line option.
@@ -272,8 +276,15 @@ PassUsers admin
 #PassSite *.google.com * android
 #PassSite .fbcdn.net* soner android
 
+# Load configuration from an include file
+# Recursive include files are not allowed. The Include option cannot be used in 
+# include files.
+#Include /etc/sslproxy/filterrules.conf
+#Include /etc/sslproxy/proxyspecs.conf
+
 # Define macro to be used in filtering rules. Macro names must start with a $ 
 # char. The macro name must be followed by words separated with spaces.
+# Recursive macro definitions are not allowed.
 #Define $macro value1 value2
 
 # Filtering rules
@@ -377,6 +388,6 @@ ProxySpec {
 	# Proxyspec specific passsites are appended to the cloned global passsites
 	PassSite example2.com
 
-	Define $admin_users soner admin
-	Pass from user $admin_users desc android to cn .fbcdn.net*
+	Define $admins soner admin
+	Pass from user $admins desc android to cn .fbcdn.net*
 }

src/sslproxy.conf.5

@@ -59,6 +59,10 @@ sslproxy takes a default action. If an option is defined outside any
 structured proxyspec, then it is used as a global default. If an option does 
 not have a command line equivalent, -o opt=val option can be used to override 
 it on the command line.
+.LP 
+Note that the ordering of options, rules, and proxyspecs in configuration 
+files (and on the command line) is important. For example, rules and 
+proxyspecs can only make use of the options defined earlier.
 .TP 
 \fBCACert STRING\fR
 Use CA cert (and key) to sign forged certs. Equivalent to -c command line option.
@@ -311,13 +315,21 @@ line. PassSite rules can search for exact or substring matches. Append an
 asterisk to the site field to search for substring match. Note that the 
 substring search is not a regex or wildcard search, and that the asterisk at 
 the end is removed before search.
+.TP 
+\fBInclude STRING\fR
+Load configuration from an include file.
+
+Recursive include files are not allowed. The Include option cannot be used in 
+include files.
 .TP
 \fBDefine STRING\fR
 Define macro to be used in filtering rules. Macro names must start with a $ 
 char. The macro name must be followed by words separated with spaces. For 
 example,
 
-Define $macro value1 value2
+	Define $macro value1 value2
+
+Recursive macro definitions are not allowed.
 .TP
 \fBDivert STRING\fR
 Divert filtering rule diverts packets to listening program, allowing SSL 
@@ -443,9 +455,9 @@ Divert|Split|Pass|Block|Match filtering rules
 .br
 
 Structured proxy specifications may consist of the options listed above. The 
-Proto, Addr, and Port options are mandatory, and equivalent to type, 
-listenaddr, and port options in one line proxyspecs, respectively. If an 
-option is not specified, the global default value is used.
+Addr and Port options are mandatory, and equivalent to listenaddr and port 
+options in one line proxyspecs, respectively. If an option is not specified, 
+the global default value is used.
 .SH "FILES"
 .LP 
 /etc/sslproxy/sslproxy.conf