ser command reference classified by command purposed, clarifications

added to listen/fork config file options

doc/seruser/seruser.sgml

@@ -1556,7 +1556,16 @@ P-hint: OUTBOUND.			    </programlisting>
 		<listitem>
 		    <para>
 			<varname>fork</varname> - If set to yes, the server will spawn children. If set to no, the main
-			process will be processing all messages (this is mainly for debugging).
+			process will be processing all messages.
+			<note>
+				<para>
+					 Disabling child spawning is useful mainly for
+					 debugging. When <varname>fork</varname> is turned off,
+					 some features are unavailable: Server is able to listen
+					 only at one address, there is no attendant process
+					 and no pid file is generated.
+				</para>
+			</note>
 		    </para>
 		</listitem>
 		<listitem>
@@ -1569,6 +1578,19 @@ P-hint: OUTBOUND.			    </programlisting>
 		<listitem>
 		    <para>
 			<varname>listen</varname> - list of all IP addresses or hostnames SER should listen on.
+			<note>
+				<para>
+					This parameter may repeat several times, then SER will
+					listen on all addresses. For example, the following
+					command-line options (equivalent to "listen" config
+					option) may be used: 
+					<command>
+						ser -l foo  -l bar -p 5061 -l x -l y 
+					</command>
+					will listen on foo:5060, bar:5061 & x:5061 & y:5061
+
+				</para>
+			</note>
 		    </para>
 		</listitem>
 		<listitem>
@@ -1693,64 +1715,40 @@ P-hint: OUTBOUND.			    </programlisting>
 	</section>
 	<section>
 	    <title>Core Commands</title>
+
+
 	    <itemizedlist>
+		<title>Command Blocks</title>
 		<listitem>
 		    <para>
-			<command>forward</command> - Forward the request to given destination.
-		    </para>
-		    <para>
-			<emphasis>Example:</emphasis> forward("foo.bar.com");
-		    </para>
-		</listitem>
-		<listitem>
-		    <para>
-			<command>drop</command> - Drop the request and stop processing.
-		    </para>
-		    <para>
-			<emphasis>Example:</emphasis> drop();
-		    </para>
-		</listitem>
-		<listitem>
-		    <para>
-			<command>send</command> - Send the message as is to the third party (without Via processing, good for
-			spying).
-		    </para>
-		    <para>
-			<emphasis>Example:</emphasis> send("foo.bar.com");
-		    </para>
-		</listitem>
-		<listitem>
-		    <para>
-			<command>log</command> - Log a message.
-		    </para>
-		    <para>
-			<emphasis>Example:</emphasis> log("This is a message\n");
-		    </para>
-		</listitem>
-		<listitem>
-		    <para>
-			<command>error</command> - Report and error (same as log but in different log level).
-		    </para>
-		    <para>
-			<emphasis>Example:</emphasis> error("This is an error message\n");
-		    </para>
-		</listitem>
-		<listitem>
-		    <para>
-			<command>route</command> - This marks a route statement in the configuration file.
+			<command>route</command> - This marks a "route block" in the configuration file. route blocks are basic building blocks of ser scrits. The contain sequences of 
+<application>SER</application> commands enclosed in parenthesses. Configuration files
+can include multiple route blocks, basic  all of them serving as a kind
+of subroutines. By default, route block 0 is entered for received request. 
+Other route blocks may be entered by calling the command <command>route(n)</command>, 
+where n is number of the block.
 		    </para>
 		    <example>
 			<title>route</title>
 			<programlisting format="linespecific">
-route {
-    forward("host", "port");
+route[1] {
+	route(2);
+}
+
+route[2] {
+    forward("host.foo.bar", 5060);
 }
 </programlisting>
 		    </example>
 		</listitem>
 		<listitem>
 		    <para>
-			<command>reply_route</command> - This marks a reply_route in the configuration statement.
+			<command>reply_route</command> - This marks a reply_route block in the configuration statement. <command>reply_route</command> blocks, similarly to <command>route</command> blocks are basic building blocks
+containing multiple <application>SER</application>commands. Unlike the <command>route</command> blocks, <command>reply_route</command> blocks are processed
+on receipt of a reply, and continue in processing original requests. They can currently
+be used only along with TM module and <command>t_on_negative</command> command. Only
+selected actions may be called from <command>reply_route</command> blocks, such as
+URI-rewriting actions.
 		    </para>
 		    <example>
 			<title>reply_route</title>
@@ -1763,14 +1761,9 @@ reply_route[1] {
 </programlisting>
 		    </example>
 		</listitem>
-		<listitem>
-		    <para>
-			<command>exec</command> - Execute an external command.
-		    </para>
-		    <para>
-			<emphasis>Example:</emphasis> exec("rm -rf /");
-		    </para>
-		</listitem>
+	    </itemizedlist>
+	    <itemizedlist>
+		<title>Flag Manipulation</title>
 		<listitem>
 		    <para>
 			<command>setflag</command> - Set flag in the message.
@@ -1800,20 +1793,9 @@ if (isflagset(1)) {
 </programlisting>
 		    </example>
 		</listitem>
-		<listitem>
-		    <para>
-			<command>len_gt</command> - If length of the message is greater than value given as parameter, the
-			command will return 1 (indicating true). Otherwise -1 (indicating false) will be returned.
-		    </para>
-		    <example>
-			<title>len_gt</title>
-			<programlisting format="linespecific">
-if (len_gt(1000)) {
-    ....
-};
-</programlisting>
-		    </example>
-		</listitem>
+	    </itemizedlist>
+	    <itemizedlist>
+		<title>URI Manipulation</title>
 		<listitem>
 		    <para>
 			<command>rewritehost | sethost | seth</command> - Rewrite host part of the Request URI.
@@ -1895,9 +1877,74 @@ if (len_gt(1000)) {
 			<emphasis>Example:</emphasis> append_branch("sip:foo.bar.com");
 		    </para>
 		</listitem>
+	    </itemizedlist>
+	    <itemizedlist>
+		<title>Message Forwarding</title>
+		<listitem>
+		    <para>
+			<command>forward(uri, port)</command> - Forward the request to given 
+			destination.  The uri and port parameters may take values 'uri:host'
+			and 'uri:port' respectively, in which case SER forwards to destination
+			set in current URI.
+		    </para>
+		    <para>
+			<emphasis>Example:</emphasis> forward("foo.bar.com");
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			<command>send</command> - Send the message as is to the third party (without Via processing, good for
+			spying).
+		    </para>
+		    <para>
+			<emphasis>Example:</emphasis> send("foo.bar.com");
+		    </para>
+		</listitem>
+	    </itemizedlist>
+	    <itemizedlist>
+		<title>Logging</title>
+		<listitem>
+		    <para>
+			<command>log</command> - Log a message.
+		    </para>
+		    <para>
+			<emphasis>Example:</emphasis> log("This is a message\n");
+		    </para>
+		</listitem>
 		<listitem>
 		    <para>
-			<command>if</command> - If statement.
+			<command>error</command> - Report and error (same as log but in different log level).
+		    </para>
+		    <para>
+			<emphasis>Example:</emphasis> error("This is an error message\n");
+		    </para>
+		</listitem>
+
+
+	    </itemizedlist>
+	    <itemizedlist>
+		<title>Processing Control</title>
+
+		<listitem>
+		    <para>
+			<command>drop</command> - Drop the request and stop processing.
+		    </para>
+		    <para>
+			<emphasis>Example:</emphasis> drop();
+		    </para>
+		</listitem>
+
+		<listitem>
+		    <para>
+			<command>route(n)</command> - call routing block route[n]{...};
+			when the routing block n finishes processing, control is passed
+			back to current block and processing continues.
+		    </para>
+		</listitem>
+
+		<listitem>
+		    <para>
+			<command>if</command> - Conditional statement.
 		    </para>
 		    <example>
 			<title>if</title>
@@ -1920,6 +1967,24 @@ if (...) {
 } else {
     ...
 };
+</programlisting>
+		    </example>
+		</listitem>
+	    </itemizedlist>
+	    <itemizedlist>
+		<title>Miscellaneous</title>
+		<listitem>
+		    <para>
+			<command>len_gt</command> - If length of the message is greater than value given as parameter, the
+			command will return 1 (indicating true). Otherwise -1 (indicating false) will be returned. It may take 'max_len' as parameter, in which case message size is limited
+to internal buffer size BUF_SIZE (3040 by default).
+		    </para>
+		    <example>
+			<title>len_gt</title>
+			<programlisting format="linespecific">
+if (len_gt(1000)) {
+    ....
+};
 </programlisting>
 		    </example>
 		</listitem>