enum: updated docs about parameters of the functions

src/modules/enum/doc/enum_admin.xml

@@ -11,19 +11,19 @@
 <!-- Enum Module User's Guide -->
 
 <chapter>
-	
+
 	<title>&adminguide;</title>
 
 	<section id="sec-overview">
 	<title>Overview</title>
 	<para>
-		Enum module implements [i_]enum_query functions that make an enum query 
+		Enum module implements [i_]enum_query functions that make an enum query
 		based on the user part of the current Request-URI. These functions
-		assume that the Request URI user part consists of an international phone number 
+		assume that the Request URI user part consists of an international phone number
 		of the form +decimal-digits, where the number of digits is at
 		least 2 and at most 20. Out of this number
-		<function moreinfo="none">enum_query</function> forms a domain name, 
-		where the digits are in reverse order and separated by dots followed by 
+		<function moreinfo="none">enum_query</function> forms a domain name,
+		where the digits are in reverse order and separated by dots followed by
 		domain suffix that by default is <quote>e164.arpa.</quote>. For example, 
 		if the user part is +35831234567, the domain
 		name will be <quote>7.6.5.4.3.2.1.3.8.5.3.e164.arpa.</quote>.
@@ -32,43 +32,43 @@
 		to branch off from the default, user-ENUM tree to an infrastructure ENUM tree.
 	</para>
 	<para>
-		After forming the domain name, 
+		After forming the domain name,
 		<function moreinfo="none">enum_query</function> queries
 		DNS for enum NAPTR records. From the possible responses
-		<function moreinfo="none">enum_query</function> chooses those records, 
-		whose flags field has string value "u", and whose services field has 
-		string value "e2u+[service:]sip" or 
-		"e2u+type[:subtype][+type[:subtype]...]" (case is ignored in both 
+		<function moreinfo="none">enum_query</function> chooses those records,
+		whose flags field has string value "u", and whose services field has
+		string value "e2u+[service:]sip" or
+		"e2u+type[:subtype][+type[:subtype]...]" (case is ignored in both
 		cases), and whose regexp field is of the form !pattern!replacement!.
 	</para>
 	<para>
-		Then <function moreinfo="none">enum_query</function> sorts the chosen 
-		NAPTR records based on their &lt;order, preference&gt;.  After sorting, 
-		<function moreinfo="none">enum_query</function> replaces the current 
-		Request URI by applying the regular expression of the most preferred NAPTR record 
-		to its user part and appends to the request new branches by applying regexp of 
+		Then <function moreinfo="none">enum_query</function> sorts the chosen
+		NAPTR records based on their &lt;order, preference&gt;.  After sorting,
+		<function moreinfo="none">enum_query</function> replaces the current
+		Request URI by applying the regular expression of the most preferred NAPTR record
+		to its user part and appends to the request new branches by applying regexp of
 		each remaining NAPTR record to the user part of the
-		current Request URI. If a new URI is a tel: URI, 
+		current Request URI. If a new URI is a tel: URI,
 		<function moreinfo="none">enum_query</function> appends to it as tel:
-		URI parameters the value of tel_uri_params module parameter. Finally, 
-		<function moreinfo="none">enum_query</function> associates a q value 
-		with each new URI based on the &lt;order, preference&gt; of the 
+		URI parameters the value of tel_uri_params module parameter. Finally,
+		<function moreinfo="none">enum_query</function> associates a q value
+		with each new URI based on the &lt;order, preference&gt; of the
 		corresponding NAPTR record.
 	</para>
 	<para>
-		When using <function moreinfo="none">enum_query</function> without any 
-		parameters, it searches for NAPTRs with service type "e2u+sip" in the 
-		default enum tree. When using 
+		When using <function moreinfo="none">enum_query</function> without any
+		parameters, it searches for NAPTRs with service type "e2u+sip" in the
+		default enum tree. When using
 		<function moreinfo="none">enum_query</function> with a single parameter, 
-		this parameter will be used as enum tree. When using 
-		<function moreinfo="none">enum_query</function> 
-		with two parameters, the functionality depends on the first letter in 
-		the second parameter. When the first letter is not a '+' sign, the 
-		second parameter will be used to search for NAPTRs with service type 
-		"e2u+parameter:sip". When the second parameter starts with a '+' sign, 
-		the ENUM lookup also supports compound NAPTRs 
-		(e.g. "e2u+voice:sip+video:sip") and searching for multiple service 
-		types within one lookup. Multiple service types must be separeted 
+		this parameter will be used as enum tree. When using
+		<function moreinfo="none">enum_query</function>
+		with two parameters, the functionality depends on the first letter in
+		the second parameter. When the first letter is not a '+' sign, the
+		second parameter will be used to search for NAPTRs with service type
+		"e2u+parameter:sip". When the second parameter starts with a '+' sign,
+		the ENUM lookup also supports compound NAPTRs
+		(e.g. "e2u+voice:sip+video:sip") and searching for multiple service
+		types within one lookup. Multiple service types must be separeted
 		by a '+' sign.
 	</para>
 	<para>
@@ -80,7 +80,7 @@
 		part of the RURI.
 	</para>
 	<para>
-		Enum query returns 1 if the current Request URI was replaced 
+		Enum query returns 1 if the current Request URI was replaced
 		and -1 if not.
 	</para>
 	<para>
@@ -93,7 +93,7 @@
 	<section>
 	<title>Dependencies</title>
 	<para>
-		The module depends on the following modules (in other words the 
+		The module depends on the following modules (in other words the
 		listed modules must be loaded before this module):
 		<itemizedlist>
 		<listitem>
@@ -109,7 +109,7 @@
 		<title><varname>domain_suffix</varname> (string)</title>
 		<para>
 		The domain suffix to be added to the domain name obtained from
-		the digits of an <acronym>E164</acronym> number. Can be overridden 
+		the digits of an <acronym>E164</acronym> number. Can be overridden
 		by a parameter to enum_query.
 		</para>
 		<para>
@@ -126,7 +126,7 @@ modparam("enum", "domain_suffix", "e1234.arpa.")
 	<section id="enum.p.tel_uri_params">
 		<title><varname>tel_uri_params</varname> (string)</title>
 		<para>
-		A string whose contents is appended to each new tel URI in the 
+		A string whose contents is appended to each new tel URI in the
 		request as tel URI parameters.
 		</para>
 		<note>
@@ -180,7 +180,7 @@ modparam("enum", "branchlabel", "i")
 	<section id="enum.p.bl_algorithm">
                 <title><varname>bl_algorithm</varname> (string)</title>
                 <para>
-                This parameter determines which algorithm the 
+                This parameter determines which algorithm the
 		<function>i_enum_query()</function> function will use
                 to select the position in the DNS tree where the infrastructure tree
                 branches off the user ENUM tree.
@@ -204,7 +204,9 @@ i.1.e164.arpa.                     IN TXT   "4"
                 </para>
                 <para>
                 If set to "ebl", i_enum_query() will look for an EBL (ENUM Branch Label) record at
-                [branchlabel].[reverse-country-code].[i_enum_suffix]. See http://www.ietf.org/internet-drafts/draft-lendl-enum-branch-location-record-00.txt for a description of that record and the
+				[branchlabel].[reverse-country-code].[i_enum_suffix].
+				See http://www.ietf.org/internet-drafts/draft-lendl-enum-branch-location-record-00.txt
+				for a description of that record and the
                 meaning of the fields. The RR type for the EBL has not been allocated yet.
                 This version of the code uses 65300. See resolve.h.
                 <example>
@@ -237,11 +239,11 @@ modparam("enum", "bl_algorithm", "txt")
 	<title>Functions</title>
 	<section id="enum.f.enum_query">
 		<title>
-		<function moreinfo="none">enum_query(["suffix"[,"service"]])</function>
+		<function moreinfo="none">enum_query(["suffix" [,"service"]])</function>
 		</title>
 		<para>
-		The function performs an enum query and rewrites the Request-URI with 
-		the result of the query. See <xref linkend="sec-overview"/> for more 
+		The function performs an enum query and rewrites the Request-URI with
+		the result of the query. See <xref linkend="sec-overview"/> for more
 		information.
 		</para>
 		<para>Meaning of the parameters is as follows:</para>
@@ -249,16 +251,19 @@ modparam("enum", "bl_algorithm", "txt")
 		<listitem>
 			<para><emphasis>suffix</emphasis> - Suffix
 	string to be appended to the domain name. String may contain
-	pseudo variables. 
+	pseudo variables.
 			</para>
 		</listitem>
 		<listitem>
 			<para><emphasis>service</emphasis> - Service
 	string to be used in the service field. String may contain
-	pseudo variables. 
+	pseudo variables.
 			</para>
 		</listitem>
 		</itemizedlist>
+		<para>
+		Parameters can include pseudo-variables.
+        </para>
 		<para>
 		This function can be used from REQUEST_ROUTE.
 		</para>
@@ -266,7 +271,7 @@ modparam("enum", "bl_algorithm", "txt")
 		<title><function moreinfo="none">enum_query</function> usage</title>
 		<programlisting format="linespecific">
 ...
-# search for "e2u+sip" in freenum.org 
+# search for "e2u+sip" in freenum.org
 enum_query("freenum.org.");
 ...
 # search for "e2u+sip" in default tree (configured as parameter)
@@ -291,12 +296,12 @@ enum_query("e164.arpa.","+sip+voice:sip");
 
 	<section id="enum.f.enum_pv_query">
 		<title>
-		<function moreinfo="none">enum_pv_query("pvar"[,"suffix"[,"service"]])</function>
+		<function moreinfo="none">enum_pv_query("pvar" [,"suffix" [,"service"]])</function>
 		</title>
 		<para>
 		The function performs an enum query on E.164 number stored
-		in its pseudo variable argument and rewrites the Request-URI with 
-		the result of the query. See <xref linkend="sec-overview"/> for more 
+		in its first argument and rewrites the Request-URI with
+		the result of the query. See <xref linkend="sec-overview"/> for more
 		information.
 		</para>
 		<para>Meaning of the parameters is as follows:</para>
@@ -308,16 +313,19 @@ enum_query("e164.arpa.","+sip+voice:sip");
 			</para>
 		</listitem>
 		<listitem>
-			<para><emphasis>suffix</emphasis> - Suffix to be appended to the 
+			<para><emphasis>suffix</emphasis> - Suffix to be appended to the
 			domain name.
 			</para>
 		</listitem>
 		<listitem>
-			<para><emphasis>service</emphasis> - Service string to be used in 
+			<para><emphasis>service</emphasis> - Service string to be used in
 			the service field.
 			</para>
 		</listitem>
 		</itemizedlist>
+		<para>
+		Parameters can include pseudo-variables.
+        </para>
 		<para>
 		This function can be used from REQUEST_ROUTE.
 		</para>
@@ -325,7 +333,7 @@ enum_query("e164.arpa.","+sip+voice:sip");
 		<title><function moreinfo="none">enum_pv_query</function> usage</title>
 		<programlisting format="linespecific">
 ...
-# search for "e2u+sip" in freenum.org 
+# search for "e2u+sip" in freenum.org
 enum_pv_query("$avp(i:100)", "freenum.org.");
 ...
 # search for "e2u+sip" in default tree (configured as parameter)
@@ -349,20 +357,23 @@ enum_pv_query("$avp(i:100)","e164.arpa.","+sip+voice:sip");
 	</section>
 
 	<section id="enum.f.i_enum_query">
-                <title>
-                <function moreinfo="none">i_enum_query(["suffix"[,"service"]])</function>
-                </title>
-                <para>
-                The function performs an enum query and rewrites the Request-URI with
-                the result of the query. This the Infrastructure-ENUM version of enum_query().
-                The only difference to enum_query() is in the calculation of the
-                FQDN where NAPTR records are looked for.
-                </para>
-                <para>
-                See ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberler-carrier-enum-01.txt
-                for the rationale behind this function.
-                </para>
-        </section>
+        <title>
+        <function moreinfo="none">i_enum_query(["suffix" [,"service"]])</function>
+        </title>
+        <para>
+        The function performs an enum query and rewrites the Request-URI with
+        the result of the query. This the Infrastructure-ENUM version of enum_query().
+        The only difference to enum_query() is in the calculation of the
+        FQDN where NAPTR records are looked for.
+		</para>
+		<para>
+		Parameters can include pseudo-variables.
+        </para>
+        <para>
+        See ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberler-carrier-enum-01.txt
+        for the rationale behind this function.
+        </para>
+     </section>
 
 	<section id="enum.f.is_from_user_enum">
 		<title><function moreinfo="none">is_from_user_enum()</function></title>