[sr-dev] git:master: Added some clarifications and additional information to the ' geoip' docs.

[Alex Balashov]

Module: sip-router
Branch: master
Commit: 8c5375ff34b111807873cf6007886219d99d34ce
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=8c5375ff34b111807873cf6007886219d99d34ce

Author: Alex Balashov <abalashov at evaristesys.com>
Committer: Alex Balashov <abalashov at evaristesys.com>
Date:   Wed Oct  6 02:51:23 2010 -0400

Added some clarifications and additional information to the 'geoip' docs.

---

 modules/geoip/README              |   37 ++++++++++++++++++++++++----------
 modules/geoip/doc/geoip_admin.xml |   39 ++++++++++++++++++++++++++++--------
 2 files changed, 56 insertions(+), 20 deletions(-)

diff --git a/modules/geoip/README b/modules/geoip/README
index 01c3d9d..11c8c73 100644
--- a/modules/geoip/README
+++ b/modules/geoip/README
@@ -10,7 +10,7 @@ Daniel-Constantin Mierla
 
    <miconda at gmail.com>
 
-   Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
+   Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
      __________________________________________________________________
 
    Table of Contents
@@ -60,12 +60,26 @@ Chapter 1. Admin Guide
 
 1. Overview
 
-   The module loads exports a new class of pseudo-variables -
-   $gip(pvc=>key) - to access results upon a query against Max Mind GeoIP
-   database.
+   This module allows real-time queries against the Max Mind GeoIP
+   database to be performed from the config script.
+
+   The Max Mind GeoIP database is a map of IP network address assignments
+   to geographical locales that can be useful -- though approximate -- in
+   identifying the physical location with which an IP host address is
+   associated on a relatively granular level.
+
+   This database itself can be obtained on a free or commercial basis
+   here. The library that interfaces with the Max Mind API, as well as
+   scripts to automate downloading of the on-disk version of the
+   open-source database is also packaged by the Debian Linux distribution
+   and its derivatives as libgeoip, and probably by other distributions as
+   well.
+
+   This module exports a new class of pseudo-variables - $gip(pvc=>key) -
+   to enable access to the results of a query to the database.
 
    Many queries can be done and store results in different containers to
-   be able to use in parallel. Database is loaded at startup in chache.
+   be able to use in parallel. Database is loaded at startup in cache.
 
 2. Dependencies
 
@@ -89,9 +103,9 @@ Chapter 1. Admin Guide
 
 3.1. path (string)
 
-   Path to GeoIP database file.
+   Path to the GeoIP database file.
 
-   Default value is "null".
+   Default value is “null”.
 
    Example 1.1. Set path parameter
 ...
@@ -104,8 +118,8 @@ modparam("geoip", "path", "/usr/local/share/GeoLiteCity.dat")
 
 4.1.  geoip_match(ipaddr, pvc)
 
-   Match ipaddr against GeoIP database and set the pvc container. The
-   function has to be called before accessing any $gip(pvc=>key).
+   Match ipaddr against the GeoIP database and set the pvc container. The
+   function has to be called before accessing a key via: $gip(pvc=>key).
 
    Example 1.2. geoip_match usage
 ...
@@ -115,8 +129,9 @@ if(geoip_match("$si", "src"))
 
 5. Exported pseudo-variables
 
-     * $gip(pvc=>key) - pvc is second parameter of geoip_match() and key
-       can be:
+     * $gip(pvc=>key) - pvc is an identifier for this query result; it is
+       designated by the second parameter of geoip_match(). The key can be
+       one of the following:
           + cc - country code
           + tz - time zone
           + zip - postal code
diff --git a/modules/geoip/doc/geoip_admin.xml b/modules/geoip/doc/geoip_admin.xml
index 89d2ede..b8c9f17 100644
--- a/modules/geoip/doc/geoip_admin.xml
+++ b/modules/geoip/doc/geoip_admin.xml
@@ -17,13 +17,32 @@
     <section>
 	<title>Overview</title>
 	<para>
-		The module loads exports a new class of pseudo-variables -
-		$gip(pvc=&gt;key) - to access results upon a query against Max Mind
-		GeoIP database.
+		This module allows real-time queries against the Max Mind GeoIP 
+		database to be performed from the config script.  
+	</para>
+	<para>
+		The Max Mind GeoIP database is a map of IP network address assignments 
+		to geographical locales that can be useful -- though approximate --
+		in identifying the physical location with which an IP host address
+		is associated on a relatively granular level.
+	</para>
+	<para>
+		This database itself can be obtained on a free or commercial basis 
+		<ulink url="http://www.maxmind.com/app/ip-location">here</ulink>.  The 
+		library that interfaces with the Max Mind API, as well as scripts to
+		automate downloading of the on-disk version of the open-source 
+		database is also packaged by the Debian Linux distribution and 
+		its derivatives as <emphasis>libgeoip</emphasis>, and probably by
+		other distributions as well.
+	</para>
+	<para>
+		This module exports a new class of pseudo-variables -
+		$gip(pvc=&gt;key) - to enable access to the results of a query to the
+		database.
 	</para>
 	<para>
 		Many queries can be done and store results in different containers to
-		be able to use in parallel. Database is loaded at startup in chache.
+		be able to use in parallel. Database is loaded at startup in cache.
 	</para>
     </section>
     <section>
@@ -61,7 +80,7 @@
 	<section>
 	    <title><varname>path</varname> (string)</title>
 	    <para>
-		Path to GeoIP database file.
+		Path to the GeoIP database file.
 	    </para>
 	    <para>
 		<emphasis>
@@ -87,8 +106,8 @@ modparam("geoip", "path", "/usr/local/share/GeoLiteCity.dat")
 		<function moreinfo="none">geoip_match(ipaddr, pvc)</function>
 	    </title>
 	    <para>
-			Match ipaddr against GeoIP database and set the pvc container. The
-			function has to be called before accessing any $gip(pvc=&gt;key).
+			Match ipaddr against the GeoIP database and set the pvc container. The
+			function has to be called before accessing a key via: $gip(pvc=&gt;key).
 	    </para>
 		<example>
 		<title><function>geoip_match</function> usage</title>
@@ -107,8 +126,10 @@ if(geoip_match("$si", "src"))
 		<title>Exported pseudo-variables</title>
 		<itemizedlist>
 			<listitem><para>
-				<emphasis>$gip(pvc=&gt;key)</emphasis> - pvc is second
-				parameter of geoip_match() and key can be:
+				<emphasis>$gip(pvc=&gt;key)</emphasis> - <emphasis>pvc</emphasis> is an 
+				identifier for this query result;  it is designated by the second 
+				parameter of geoip_match(). The <emphasis>key</emphasis> can be one of
+				the following:
 				</para>
 			<itemizedlist>
 				<listitem><para>