From 4e1089560eee7edf11f6337a195666f0e68ab0a1 Mon Sep 17 00:00:00 2001
From: Bob Grabar <bob.grabar@10gen.com>
Date: Fri, 19 Apr 2013 11:03:53 -0400
Subject: [PATCH] DOCS-1388 geospatial internals and 2d indexes

---
 source/applications/geospatial-indexes.txt | 18 +++++++++--
 source/core/geospatial-indexes.txt         | 37 ++++++++--------------
 source/reference/command/geoNear.txt       |  2 ++
 source/reference/glossary.txt              |  2 +-
 4 files changed, 31 insertions(+), 28 deletions(-)

diff --git a/source/applications/geospatial-indexes.txt b/source/applications/geospatial-indexes.txt
index 096856f2c30..79529f681ec 100644
--- a/source/applications/geospatial-indexes.txt
+++ b/source/applications/geospatial-indexes.txt
@@ -6,7 +6,7 @@ Geospatial Indexes and Queries
 
 MongoDB offers a number of indexes and query mechanisms to handle
 geospatial information. This section introduces MongoDB's geospatial
-features. 
+features.
 
 Surfaces
 --------
@@ -109,11 +109,23 @@ geospatial queries:
 
   - A compound index with only one additional field, as a suffix of the
     ``2d`` index field
-    
+
+Geospatial Indexes and Sharding
+-------------------------------
+
+You *cannot* use a geospatial index as the :term:`shard key` index.
+
+You can create and maintain a geospatial index on
+a sharded collection if using different fields as the shard key.
+
+Queries using :operator:`$near` are not supported for sharded
+collections. Use :dbcommand:`geoNear` instead. You also can query for
+geospatial data using :operator:`$geoWithin`.
+
 Additional Resources
 --------------------
 
-Consider the following pages for complete documentation of geospatial
+The following pages provide complete documentation for geospatial
 indexes and queries:
 
 .. toctree::
diff --git a/source/core/geospatial-indexes.txt b/source/core/geospatial-indexes.txt
index 3e39e953edc..c2d63114607 100644
--- a/source/core/geospatial-indexes.txt
+++ b/source/core/geospatial-indexes.txt
@@ -1,36 +1,25 @@
-==========================
-Geospatial Index Internals
-==========================
+======================
+``2d`` Index Internals
+======================
 
 .. default-domain:: mongodb
 
 This document provides a more in-depth explanation of the internals of MongoDB's
-geospatial features. This material is not necessary for normal operations
+``2d`` geospatial indexes. This material is not necessary for normal operations
 or application development but may be useful for troubleshooting and for
-further understanding MongoDB's behavior and approach.
-
-Geospatial Indexes and Sharding
--------------------------------
-
-You *cannot* use a geospatial index as a :term:`shard key` when sharding
-a collection. However, you can create and maintain a geospatial index on
-a sharded collection by using a different field as the shard key. You
-can query for geospatial data using :dbcommand:`geoNear` and
-:operator:`$geoWithin`.
-
-Queries using :operator:`$near` are not supported for sharded
-collections. Use :dbcommand:`geoNear` instead.
+further understanding.
 
 .. _geospatial-indexes-geohash:
 
-Geohash Values
---------------
+Calculation of Geohash Values for ``2d`` Indexes
+------------------------------------------------
 
-When you create a geospatial index on legacy coordinate pairs, MongoDB computes
+When you create a geospatial index on
+:term:`legacy coordinate pairs <legacy coordinate pairs>`, MongoDB computes
 :term:`geohash` values for the coordinate pairs within the specified
-:ref:`range <geospatial-indexes-range>` and indexes the geohash values.
+:ref:`location range <geospatial-indexes-range>` and then indexes the geohash values.
 
-To calculate a geohash value, continuously divide a 2D map into
+To calculate a geohash value, recursively divide a two-dimensional map into
 quadrants. Then assign each quadrant a two-bit value. For example, a
 two-bit representation of four quadrants would be:
 
@@ -62,8 +51,8 @@ geospatial index.
 
 .. _geospatial-indexes-multi-location:
 
-Multi-location Documents for 2D Indexes
----------------------------------------
+Multi-location Documents for ``2d`` Indexes
+-------------------------------------------
 
 .. versionadded:: 2.0
    Support for multiple locations in a document.
diff --git a/source/reference/command/geoNear.txt b/source/reference/command/geoNear.txt
index f37056b31b1..901c7853f5f 100644
--- a/source/reference/command/geoNear.txt
+++ b/source/reference/command/geoNear.txt
@@ -6,6 +6,8 @@ geoNear
 
 .. dbcommand:: geoNear
 
+   The :dbcommand:`geoNear` command specifies a point for which a
+   geospatial query returns the 100 closest documents.
    The :dbcommand:`geoNear` command provides an alternative to the
    :operator:`$near` operator. In addition to the functionality of
    :operator:`$near`, :dbcommand:`geoNear` returns additional diagnostic
diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt
index 718e0a4dfcd..1f786c43767 100644
--- a/source/reference/glossary.txt
+++ b/source/reference/glossary.txt
@@ -813,7 +813,7 @@ Glossary
       creation. MongoDB uses ObjectId values as the default values for
       :term:`_id` fields.
 
-   Geohash
+   geohash
       A value is a binary representation of the location on a
       coordinate grid.