From ab47d24b93fc638ead3091bf51dbb0d831e502fa Mon Sep 17 00:00:00 2001
From: kay <kay.kim@10gen.com>
Date: Tue, 27 Nov 2012 19:54:58 -0500
Subject: [PATCH 1/2] DOCS-800 added dot notation documentation

---
 source/applications/read.txt    |  63 ++++++++-----
 source/applications/update.txt  |   7 +-
 source/core/document.txt        |  93 +++++++++++++++++--
 source/core/read-operations.txt | 156 +++++++++++++++++++++++++++++---
 source/reference/glossary.txt   |  19 ++++
 5 files changed, 293 insertions(+), 45 deletions(-)

diff --git a/source/applications/read.txt b/source/applications/read.txt
index 8b2ea9b58db..9b44e99aa1d 100644
--- a/source/applications/read.txt
+++ b/source/applications/read.txt
@@ -124,9 +124,11 @@ Consider the following examples that illustrate the use of the
           }
        )
 
+  *Arrays*
+
   - The following operation returns all documents in the ``bios``
     collection where the array field ``contribs`` contains the element
-    ``UNIX``:
+    ``'UNIX'``:
 
     .. code-block:: javascript
 
@@ -135,11 +137,36 @@ Consider the following examples that illustrate the use of the
             contribs: 'UNIX'
           }
        )
+       
+  - The following operation returns all documents in the ``bios``
+    collection where ``awards`` array contains a subdocument element
+    that contains the ``award`` field equal to ``'Turing Award'`` and the
+    ``year`` field greater than 1980:
+
+    .. code-block:: javascript
+
+       db.bios.find(
+          {
+            awards: {
+                      $elemMatch: {
+                           award: 'Turing Award',
+                           year: { $gt: 1980 }
+                      }
+            }
+          }
+       )
+
+    For more examples on accessing arrays, see :ref:`query documents
+    for arrays <document-query-arrays>` and :ref:`read operations
+    <read-operations-dot-notation-arrays>`.
+
+  *Subdocuments*
 
   - The following operation returns all documents in the ``bios``
     collection where the subdocument ``name`` contains a field
-    ``first`` with the value ``Yukihiro`` and a field ``last`` with the
-    value ``Matsumoto``:
+    ``first`` with the value ``'Yukihiro'`` and a field ``last`` with
+    the value ``'Matsumoto'``; the query uses :term:`dot-notation` to
+    access fields in a subdocument:
 
     .. code-block:: javascript
 
@@ -151,8 +178,8 @@ Consider the following examples that illustrate the use of the
        )
 
     The query matches the document where the ``name`` field contains a
-    subdocument with the field ``first`` with the value ``Yukihiro``
-    and a field ``last`` with the value ``Matsumoto``. For instance,
+    subdocument with the field ``first`` with the value ``'Yukihiro'``
+    and a field ``last`` with the value ``'Matsumoto'``. For instance,
     the query would match documents with ``name`` fields that
     held either of the following values:
 
@@ -201,6 +228,12 @@ Consider the following examples that illustrate the use of the
          first: 'Yukihiro'
        }
 
+    For more examples on accessing subdocuments, see :ref:`query
+    documents for subdocuments <document-query-subdocuments>` and
+    :ref:`read operations <read-operations-dot-notation-subdocuments>`.
+
+  *Compound Query Criteria*
+  
   - The following operation returns all documents in the ``bios``
     collection where either the field ``first`` in the sub-document
     ``name`` starts with the letter ``G`` **or** where the field
@@ -230,24 +263,6 @@ Consider the following examples that illustrate the use of the
           }
        )
 
-  - The following operation returns all documents in the ``bios``
-    collection where ``awards`` array contains a subdocument element
-    that contains the ``award`` field equal to ``Turing Award`` and the
-    ``year`` field greater than 1980:
-
-    .. code-block:: javascript
-
-       db.bios.find(
-          {
-            awards: {
-                      $elemMatch: {
-                           award: 'Turing Award',
-                           year: { $gt: 1980 }
-                      }
-            }
-          }
-       )
-
 - If there is a ``<projection>`` argument, the :method:`find()
   <db.collection.find()>` method returns only those fields as specified
   in the ``<projection>`` argument to include or exclude:
@@ -282,7 +297,7 @@ Consider the following examples that illustrate the use of the
 
   - The following operation finds the documents in the ``bios``
     collection where the ``contribs`` field contains the element
-    ``OOP`` and returns all fields *except* the ``_id`` field, the
+    ``'OOP'`` and returns all fields *except* the ``_id`` field, the
     ``first`` field in the ``name`` subdocument, and the ``birth``
     field from the matching documents:
 
diff --git a/source/applications/update.txt b/source/applications/update.txt
index 8f74b99c028..29c7aed3ef0 100644
--- a/source/applications/update.txt
+++ b/source/applications/update.txt
@@ -161,8 +161,8 @@ Consider the following examples that illustrate the use of the
   field:
 
   - The :method:`update() <db.collection.update()>` method can perform
-    the update using the position of the element. Arrays in MongoDB are
-    zero-based.
+    the update using the position of the element and
+    :term:`dot-notation`. Arrays in MongoDB are zero-based.
 
     The following operation queries the ``bios`` collection for
     the first document with ``_id`` field equal to ``1`` and updates the
@@ -196,8 +196,7 @@ Consider the following examples that illustrate the use of the
 
   - The :method:`update() <db.collection.update()>` method can perform
     the update of an array that contains subdocuments by using the
-    :operator:`$` positional operator and the :wiki:`dot notation
-    <Dot+Notation+(Reaching+into+Objects)>`.
+    :operator:`$` positional operator and the :term:`dot-notation`.
 
     The following operation queries the ``bios`` collection for the first
     document where the ``_id`` field equals ``6`` and the ``awards``
diff --git a/source/core/document.txt b/source/core/document.txt
index ce2dd4bb5f8..80d5b0e864b 100644
--- a/source/core/document.txt
+++ b/source/core/document.txt
@@ -79,7 +79,7 @@ The document contains the following fields:
 
 - ``_id`` that holds an *ObjectId*.
 
-- ``name`` that holds a *sub-document* that contains the fields
+- ``name`` that holds a *subdocument* that contains the fields
   ``first`` and ``last``.
 
 - ``birth`` and ``death``, which both have *Date* types.
@@ -246,6 +246,9 @@ Consider the following examples of query documents:
 
      { _id: 1, name: { first: 'John', last: 'Backus' } }
 
+  The ``name`` field must match the document exactly, including the
+  order of the fields.
+
 - The following document specifies the compound query criteria where
   ``_id`` is equal to ``1`` **or** the ``name`` field equals the
   document ``{ first: 'John', last: 'Backus' }``:
@@ -254,6 +257,79 @@ Consider the following examples of query documents:
 
      { $or: [ { _id: 1 }, { name: { first: 'John', last: 'Backus' } } ] }
 
+  The ``name`` field must match the document exactly, including the
+  order of the fields.
+
+.. _document-query-arrays:
+
+*Query Documents for Arrays*
+
+You can specify query criteria for arrays at the array level and, with
+:term:`dot-notation`, at the element level:
+
+- The following document specifies the query criteria where
+  ``contribs`` matches exactly the array ``[ 'Fortran', 'ALGOL',
+  'Backus-Naur Form', 'FP' ]``, including the order of the elements:
+
+  .. code-block:: javascript
+  
+     { contribs: [ 'Fortran', 'ALGOL', 'Backus-Naur Form', 'FP' ] }
+
+- The following document specifies the query criteria where the value
+  of ``contribs`` is an array that contains as one of its element
+  ``'ALGOL'``:
+
+  .. code-block:: javascript
+
+    { contribs: 'ALGOL' }
+
+- The following document specifies the query criteria where
+  ``contribs`` contains an element ``'ALGOL'`` in the second position.
+  Array indexes are zero-based:
+
+  .. code-block:: javascript
+
+     { 'contribs.1': 'ALGOL' }
+
+See :ref:`read operations <read-operations-dot-notation-arrays>` for more
+examples with arrays.
+
+.. _document-query-subdocuments:
+
+*Query Documents for Subdocuments*
+
+You can specify query criteria for subdocuments at the subdocument
+level and, with :term:`dot-notation`, at the field level:
+
+- The following document specifies the query criteria where the value
+  of the field ``name`` is a subdocument that contains *only* the field
+  ``first`` equal to ``'John'`` and the field ``last`` equal to
+  ``'Backus'``, in that order.
+
+  .. code-block:: javascript
+
+     { name: { first: 'John', last: 'Backus' } }
+
+- The following document specifies the query criteria where the value
+  of the field ``name`` is a subdocument that contains the field
+  ``first`` equal to ``'John'`` and may contain other fields:
+
+  .. code-block:: javascript
+
+     { 'name.first': 'John' }
+
+- The following document specifies the query criteria where the value
+  of the field ``awards`` is an array that contains, as one of its
+  elements, a subdocument that contains the field ``award`` equal to
+  ``'National Medal of Science'`` and may contain other fields:
+
+  .. code-block:: javascript
+
+     { 'awards.award': 'National Medal of Science' }
+
+See :ref:`read operations <read-operations-dot-notation-subdocuments>` for
+more examples with subdocuments.
+                
 When passed as an argument to methods such as the :method:`find()
 <db.collection.find()>` method, the :method:`remove()
 <db.collection.remove()>` method, or the :method:`update()
@@ -295,7 +371,8 @@ When passed as an argument to the :method:`update()
 
 - Modifies the field ``name`` whose value is another document.
   Specifically, the :operator:`$set` operator updates the ``middle``
-  field in the ``name`` subdocument.
+  field in the ``name`` subdocument. The document uses
+  :term:`dot-notation` to access a field in a subdocument.
 
 - Adds an element to the field ``awards`` whose value is an array.
   Specifically, the :operator:`$push` operator adds another document as
@@ -315,6 +392,10 @@ When passed as an argument to the :method:`update()
       }
    )
 
+For additional examples of updates that involve array elements,
+including where the elements are documents, see the :operator:`$`
+positional operator.
+
 .. _documents-index:
 .. _document-index-specification:
 
@@ -335,9 +416,10 @@ Index documents contain field and value pairs, in the following form:
 
 - ``value`` is either 1 for ascending or -1 for descending.
 
-The following document specifies the :ref:`multi-key index <index-type-multi-key>` on the ``_id``
-field and the ``last`` field contained in the subdocument ``name``
-field:
+The following document specifies the :ref:`multi-key index
+<index-type-multi-key>` on the ``_id`` field and the ``last`` field
+contained in the subdocument ``name`` field; the document uses
+:term:`dot-notation` to access a field in a subdocument:
 
 .. code-block:: javascript
 
@@ -355,7 +437,6 @@ the index to create:
    </core/read-operations>` and :doc:`write </core/write-operations>`
    operations.
 
-
 .. _documents-sort-order:
 
 Sort Order Specification Documents
diff --git a/source/core/read-operations.txt b/source/core/read-operations.txt
index c13048dd6e3..985ae9b2bdc 100644
--- a/source/core/read-operations.txt
+++ b/source/core/read-operations.txt
@@ -134,15 +134,6 @@ collection of documents named ``inventory``:
 
      db.inventory.find( { type: "snacks" } )
 
-  When the field holds an array an equality match will select documents if at
-  least *one* element in the array match the specified value. In the
-  following example, the query will match all documents where the array
-  in the ``tags`` field contains the element ``fruit``:
-
-  .. code-block:: javascript
-
-     db.inventory.find( { tags: "fruit" } )
-
 - A single-clause query document can also select all documents in a
   collection given a condition or set of conditions for one field in
   the collection's documents. Use the :ref:`query operators
@@ -170,7 +161,7 @@ collection of documents named ``inventory``:
 
   In the following example, the query document specifies an equality
   match on a single field, followed by a range of values for a second
-  field using a :ref:`comparison operator <query-selectors-comparison>`.
+  field using a :ref:`comparison operator <query-selectors-comparison>`:
 
   .. code-block:: javascript
 
@@ -209,6 +200,147 @@ collection of documents named ``inventory``:
                                                { price: { $lt: 9.95 } } ]
                          } )
 
+.. _read-operations-dot-notation-arrays:
+
+*Arrays*
+
+When the field holds an array, you can query at the array level and at
+the element level:
+
+- Equality match at the array level will select documents if the array
+  matches exactly the specified array, including the element order. In
+  the following example, the query will match all documents where the
+  value of the field ``tags`` is an array with only three elements,
+  ``'fruit'``, ``'food'``, and ``'citrus'``, in that order:
+
+  .. code-block:: javascript
+
+     db.inventory.find( { tags: [ 'fruit', 'food', 'citrus' ] } )
+
+- Equality match at the element level can either check if the array
+  contains at least *one* element with the specified value or if the
+  element at a specified position equals the specified value.
+
+  In the following example, the query will match all documents where
+  the value of the field ``tags`` is an array that contains, as one of
+  its elements, the element ``'fruit'``:
+
+  .. code-block:: javascript
+
+     db.inventory.find( { tags: 'fruit' } )
+
+  In the following example, the query uses the :term:`dot-notation` to match
+  all documents where the value of the ``tags`` field is an array whose
+  first element equals ``'fruit'``:
+
+  .. code-block:: javascript
+
+     db.inventory.find( { 'tags.0' : 'fruit' } )
+
+.. _read-operations-dot-notation-subdocuments:
+
+*Subdocuments*
+
+When the field holds a subdocument, you can query at the subdocument
+level or, with the use of :term:`dot-notation`, at the fields of the
+subdocument level:
+
+- Equality match at the subdocument level will select documents if the
+  subdocument matches *exactly* the specified subdocument, including the
+  field order.
+
+  In the following example, the query will match all documents where
+  the value of the field ``producer`` is a subdocument that contains
+  *only* the field ``company`` with the value ``'ABC123'`` and the field
+  ``address`` with the value ``'123 Street'``, in the exact order
+
+  .. code-block:: javascript
+
+     db.inventory.find( {
+                          producer: {
+                                      company: 'ABC123',
+                                      address: '123 Street'
+                                    } 
+                        }
+                      )
+
+- Equality match at the field level for subdocuments will select
+  documents if the subdocument contains a field that matches the
+  specified value:
+
+  In the following example, the query uses the :term:`dot-notation` to match
+  all documents where the value of the field ``producer`` is a
+  subdocument that contains a field ``company`` with the value
+  ``'ABC123'`` and may contain other fields:
+
+  .. code-block:: javascript
+
+     db.inventory.find( { 'producer.company': 'ABC123' } )
+
+.. _read-operations-dot-notation-array-of-subdocuments:
+
+*Array of Subdocuments*
+
+When a field contains an array of subdocuments you can use
+:term:`dot-notation` to query by the fields of the subdocument.
+
+- If you know the index position of the subdocument, you can specify
+  the array position.
+
+  The following example selects all documents where the ``memos``
+  contains an array whose first element (i.e. index is ``0``) is a
+  subdocument with the field ``by`` with the value ``'shipping'``:
+
+  .. code-block:: javascript
+
+     db.inventory.find( { 'memos.0.by': 'shipping' } )
+
+- If you do not know the specific index position, concatenate the array
+  name with the dot (``.``) and the field name.
+
+  The following example selects all documents where the ``memos`` field
+  contains an array that contains at least one subdocument with the
+  field ``by`` with the value ``'shipping'``:
+
+  .. code-block:: javascript
+
+     db.inventory.find( { 'memos.by': 'shipping' } )
+
+- To match by multiple fields in the subdocument, you can use either
+  dot-notation or the :doc:`$elemMatch </reference/operator/elemMatch>`
+  operator:
+
+  The following example uses dot-notation to query for documents
+  where the value of the ``memos`` field is an array that has at least
+  one subdocument that contains the field ``memo`` equal to ``'on time'``
+  and the field ``by`` equal to ``'shipping'``:
+
+  .. code-block:: javascript
+
+     db.inventory.find(
+                        {
+                          'memos.memo': 'on time',
+                          'memos.by': 'shipping'
+                        }
+                      )
+
+  The following example uses :doc:`$elemMatch
+  </reference/operator/elemMatch>` to query for documents where the
+  value of the ``memos`` field is an array that has at least one
+  subdocument that contains the field ``memo`` equal to ``'on time'`` and
+  the field ``by`` equal to ``'shipping'``:
+
+  .. code-block:: javascript
+  
+     db.inventory.find( { memos: {
+                                   $elemMatch: {
+                                                 memo : 'on time',
+                                                 by: 'shipping'
+                                               }
+                                 }
+                        }
+                      )
+
 Refer to the :doc:`/reference/operator` document for the complete
 list of query operators and :doc:`/reference/operators` for complete
 documentation of all query operators.
@@ -309,7 +441,9 @@ operation:
 
    db.collection.ensureIndex( { <field1>: <order>, <field2>: <order>, ... } )
 
-- The ``field`` specifies the field to index.
+- The ``field`` specifies the field to index. The field may be a field
+  from a subdocument, using :term:`dot-notation` to specify subdocument
+  fields.
 
   You can create an index on a single field or a :ref:`compound index
   <index-type-compound>` that includes multiple fields in the index.
diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt
index e2b2ca53c46..e1e626a0289 100644
--- a/source/reference/glossary.txt
+++ b/source/reference/glossary.txt
@@ -903,3 +903,22 @@ Glossary
       A system call that flushes all dirty, in-memory pages to
       disk. MongoDB calls ``fsync()`` on its database files at least
       every 60 seconds.
+
+   dot-notation
+      MongoDB uses the *dot-notation* to access the elements of an array and
+      to access the fields of a subdocument.
+
+      To access an element of an array by the zero-based index position, you
+      concatenate the array name with the dot (``.``) and zero-based index
+      position:
+
+      .. code-block:: javascript
+
+         '<array>.<index>'
+
+      To access a field of a subdocument with *dot-notation*, you concatenate
+      the subdocument name with the dot (``.``) and the field name:
+
+      .. code-block:: javascript
+
+         '<subdocument>.<field>'

From cbd983a9ee4b1ca48eb485aeb516abe3adf4d5ed Mon Sep 17 00:00:00 2001
From: kay <kay.kim@10gen.com>
Date: Wed, 28 Nov 2012 15:27:25 -0500
Subject: [PATCH 2/2] DOCS-800 dot-notation edits

---
 source/applications/read.txt           |  30 ++--
 source/applications/update.txt         |   7 +-
 source/core/document.txt               | 194 +++++++++----------------
 source/core/read-operations.txt        |  99 +++++++------
 source/includes/fact-dot-notation.rst  |  17 +++
 source/includes/fact-write-concern.rst |   4 -
 source/reference/glossary.txt          |  20 +--
 7 files changed, 154 insertions(+), 217 deletions(-)
 create mode 100644 source/includes/fact-dot-notation.rst

diff --git a/source/applications/read.txt b/source/applications/read.txt
index 9b44e99aa1d..35f4d230d68 100644
--- a/source/applications/read.txt
+++ b/source/applications/read.txt
@@ -124,8 +124,6 @@ Consider the following examples that illustrate the use of the
           }
        )
 
-  *Arrays*
-
   - The following operation returns all documents in the ``bios``
     collection where the array field ``contribs`` contains the element
     ``'UNIX'``:
@@ -156,16 +154,10 @@ Consider the following examples that illustrate the use of the
           }
        )
 
-    For more examples on accessing arrays, see :ref:`query documents
-    for arrays <document-query-arrays>` and :ref:`read operations
-    <read-operations-dot-notation-arrays>`.
-
-  *Subdocuments*
-
   - The following operation returns all documents in the ``bios``
     collection where the subdocument ``name`` contains a field
     ``first`` with the value ``'Yukihiro'`` and a field ``last`` with
-    the value ``'Matsumoto'``; the query uses :term:`dot-notation` to
+    the value ``'Matsumoto'``; the query uses :term:`dot notation` to
     access fields in a subdocument:
 
     .. code-block:: javascript
@@ -228,12 +220,6 @@ Consider the following examples that illustrate the use of the
          first: 'Yukihiro'
        }
 
-    For more examples on accessing subdocuments, see :ref:`query
-    documents for subdocuments <document-query-subdocuments>` and
-    :ref:`read operations <read-operations-dot-notation-subdocuments>`.
-
-  *Compound Query Criteria*
-  
   - The following operation returns all documents in the ``bios``
     collection where either the field ``first`` in the sub-document
     ``name`` starts with the letter ``G`` **or** where the field
@@ -263,6 +249,11 @@ Consider the following examples that illustrate the use of the
           }
        )
 
+    The query uses the comma to specify the logical AND for criteria on
+    different fields ``contribs`` and ``name.first``. For multiple AND
+    criteria on the same field, use the :operator:`$and` operator
+    instead of the comma.
+
 - If there is a ``<projection>`` argument, the :method:`find()
   <db.collection.find()>` method returns only those fields as specified
   in the ``<projection>`` argument to include or exclude:
@@ -323,6 +314,15 @@ Consider the following examples that illustrate the use of the
           }
        )
 
+.. seealso::
+
+   - :term:`dot notation` for information on dot notation
+
+   - :ref:`read-operations-arrays` for more examples on accessing arrays
+
+   - :ref:`read-operations-subdocuments` for more examples on accessing
+     subdocuments
+
 Cursor
 ~~~~~~
 
diff --git a/source/applications/update.txt b/source/applications/update.txt
index 29c7aed3ef0..5535d9ff450 100644
--- a/source/applications/update.txt
+++ b/source/applications/update.txt
@@ -73,7 +73,8 @@ Consider the following examples that illustrate the use of the
 - If the ``<update>`` argument contains only :ref:`update operator
   <update-operators>` expressions such as the :operator:`$set` operator
   expression, the :method:`update() <db.collection.update()>` method
-  updates the corresponding fields in the document.
+  updates the corresponding fields in the document. To update fields in
+  subdocuments, MongoDB uses :term:`dot notation`. 
 
   The following operation queries the ``bios`` collection for the first
   document that has an ``_id`` field equal to ``1`` and sets the field
@@ -162,7 +163,7 @@ Consider the following examples that illustrate the use of the
 
   - The :method:`update() <db.collection.update()>` method can perform
     the update using the position of the element and
-    :term:`dot-notation`. Arrays in MongoDB are zero-based.
+    :term:`dot notation`. Arrays in MongoDB are zero-based.
 
     The following operation queries the ``bios`` collection for
     the first document with ``_id`` field equal to ``1`` and updates the
@@ -196,7 +197,7 @@ Consider the following examples that illustrate the use of the
 
   - The :method:`update() <db.collection.update()>` method can perform
     the update of an array that contains subdocuments by using the
-    :operator:`$` positional operator and the :term:`dot-notation`.
+    positional operator (i.e. :operator:`$`) and the :term:`dot notation`.
 
     The following operation queries the ``bios`` collection for the first
     document where the ``_id`` field equals ``6`` and the ``awards``
diff --git a/source/core/document.txt b/source/core/document.txt
index 80d5b0e864b..a9f03c3ff98 100644
--- a/source/core/document.txt
+++ b/source/core/document.txt
@@ -56,10 +56,10 @@ the following structure:
       fieldN: valueN
    }
 
-Having support for the full range of :term:`BSON types`, MongoDB
-documents may contain field and value pairs where the value can be
-another document, an array, an array of documents as well as the basic
-types such as ``Double``, ``String``, and ``Date``. See also
+Having support for the full range of BSON types, MongoDB documents may
+contain field and value pairs where the value can be another document,
+an array, an array of documents as well as the basic types such as
+``Double``, ``String``, and ``Date``. See also
 :ref:`document-bson-type-considerations`.
 
 Consider the following document that contains values of varying types:
@@ -88,6 +88,11 @@ The document contains the following fields:
 
 - ``views`` that holds a value of *NumberLong* type.
 
+.. _document-type-operators:
+
+Type Operators
+~~~~~~~~~~~~~~
+
 To determine the type of fields, the :program:`mongo` shell provides
 the following operators: 
 
@@ -119,6 +124,24 @@ the following operators:
      In this case ``typeof`` will return the more generic ``object``
      type rather than ``ObjectId`` type.
 
+.. _document-dot-notation:
+
+Dot Notation
+~~~~~~~~~~~~
+
+.. include:: /includes/fact-dot-notation.rst
+
+.. seealso::
+
+   - :ref:`read-operations-subdocuments` for dot notation examples
+     with subdocuments.
+
+   - :ref:`read-operations-arrays` for dot notation examples with
+     arrays.
+
+   - :ref:`read-operations-arrays-of-subdocuments` for dot notation
+     examples with arrays of subdocuments.
+     
 Document Types in MongoDB
 -------------------------
 
@@ -215,121 +238,11 @@ Query Specification Documents
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Query documents specify the conditions that determine which records to
-select for read, update, and delete operations. You can use field and
-value expressions to specify the equality condition and :doc:`query
-operator </reference/operators>` expressions to specify additional
-conditions. Refer to :doc:`read </applications/read>`, :doc:`update
-</applications/update>`, and :doc:`delete </applications/delete>` pages
-for more examples.
-
-Consider the following examples of query documents:
-
-- The following document specifies the query criteria where ``_id`` is
-  equal to ``1``:
-
-  .. code-block:: javascript
-
-     { _id: 1 }
-
-- The following document specifies the query criteria where ``_id`` is
-  greater than ``3``:
-
-  .. code-block:: javascript
-
-     { _id: { $gt: 3 } }
-
-- The following document specifies the compound query criteria where
-  ``_id`` is equal to ``1`` **and** the ``name`` field equals the
-  document ``{ first: 'John', last: 'Backus' }``:
-
-  .. code-block:: javascript
-
-     { _id: 1, name: { first: 'John', last: 'Backus' } }
-
-  The ``name`` field must match the document exactly, including the
-  order of the fields.
-
-- The following document specifies the compound query criteria where
-  ``_id`` is equal to ``1`` **or** the ``name`` field equals the
-  document ``{ first: 'John', last: 'Backus' }``:
-
-  .. code-block:: javascript
-
-     { $or: [ { _id: 1 }, { name: { first: 'John', last: 'Backus' } } ] }
-
-  The ``name`` field must match the document exactly, including the
-  order of the fields.
-
-.. _document-query-arrays:
-
-*Query Documents for Arrays*
-
-You can specify query criteria for arrays at the array level and, with
-:term:`dot-notation`, at the element level:
-
-- The following document specifies the query criteria where
-  ``contribs`` matches exactly the array ``[ 'Fortran', 'ALGOL',
-  'Backus-Naur Form', 'FP' ]``, including the order of the elements:
-
-  .. code-block:: javascript
-  
-     { contribs: [ 'Fortran', 'ALGOL', 'Backus-Naur Form', 'FP' ] }
-
-- The following document specifies the query criteria where the value
-  of ``contribs`` is an array that contains as one of its element
-  ``'ALGOL'``:
-
-  .. code-block:: javascript
-
-    { contribs: 'ALGOL' }
-
-- The following document specifies the query criteria where
-  ``contribs`` contains an element ``'ALGOL'`` in the second position.
-  Array indexes are zero-based:
-
-  .. code-block:: javascript
-
-     { 'contribs.1': 'ALGOL' }
-
-See :ref:`read operations <read-operations-dot-notation-arrays>` for more
-examples with arrays.
-
-.. _document-query-subdocuments:
-
-*Query Documents for Subdocuments*
-
-You can specify query criteria for subdocuments at the subdocument
-level and, with :term:`dot-notation`, at the field level:
-
-- The following document specifies the query criteria where the value
-  of the field ``name`` is a subdocument that contains *only* the field
-  ``first`` equal to ``'John'`` and the field ``last`` equal to
-  ``'Backus'``, in that order.
-
-  .. code-block:: javascript
-
-     { name: { first: 'John', last: 'Backus' } }
+select for read, update, and delete operations. You can use
+``<field>:<value>`` expressions to specify the equality condition and
+:doc:`query operator </reference/operators>` expressions to specify
+additional conditions.
 
-- The following document specifies the query criteria where the value
-  of the field ``name`` is a subdocument that contains the field
-  ``first`` equal to ``'John'`` and may contain other fields:
-
-  .. code-block:: javascript
-
-     { 'name.first': 'John' }
-
-- The following document specifies the query criteria where the value
-  of the field ``awards`` is an array that contains, as one of its
-  elements, a subdocument that contains the field ``award`` equal to
-  ``'National Medal of Science'`` and may contain other fields:
-
-  .. code-block:: javascript
-
-     { 'awards.award': 'National Medal of Science' }
-
-See :ref:`read operations <read-operations-dot-notation-subdocuments>` for
-more examples with subdocuments.
-                
 When passed as an argument to methods such as the :method:`find()
 <db.collection.find()>` method, the :method:`remove()
 <db.collection.remove()>` method, or the :method:`update()
@@ -341,7 +254,20 @@ for MongoDB to return, remove, or update, as in the following:
    db.bios.find( { _id: 1 } )
    db.bios.remove( { _id: { $gt: 3 } } )
    db.bios.update( { _id: 1, name: { first: 'John', last: 'Backus' } },
-                       ... )
+                   <update>,
+                   <options> )
+
+.. seealso::
+
+   - :ref:`read-operations-query-argument` and
+     :doc:`/applications/read` for more examples on selecting documents
+     for reads.
+
+   - :doc:`/applications/update` for more examples on
+     selecting documents for updates.
+
+   - :doc:`/applications/delete` for more examples on selecting
+     documents for deletes.
 
 .. _documents-update-actions:
 
@@ -352,14 +278,14 @@ Update documents specify the data modifications to perform during
 an :method:`update() <db.collection.update()>` operation to modify
 existing records in a collection. You can use :ref:`update operators
 <update-operators>` to specify the exact actions to perform on the
-document fields. See the :ref:`update operators <update-operators>`
-page for the available update operators and syntax.
+document fields.
 
 Consider the update document example:
 
 .. code-block:: javascript
 
-   { $set: { 'name.middle': 'Warner' },
+   {
+     $set: { 'name.middle': 'Warner' },
      $push: { awards: { award: 'IBM Fellow',
                         year: '1963',
                         by: 'IBM' }
@@ -371,8 +297,8 @@ When passed as an argument to the :method:`update()
 
 - Modifies the field ``name`` whose value is another document.
   Specifically, the :operator:`$set` operator updates the ``middle``
-  field in the ``name`` subdocument. The document uses
-  :term:`dot-notation` to access a field in a subdocument.
+  field in the ``name`` subdocument. The document uses :ref:`dot
+  notation <document-dot-notation>` to access a field in a subdocument.
 
 - Adds an element to the field ``awards`` whose value is an array.
   Specifically, the :operator:`$push` operator adds another document as
@@ -382,7 +308,8 @@ When passed as an argument to the :method:`update()
 
    db.bios.update(
       { _id: 1 },
-      { $set: { 'name.middle': 'Warner' },
+      {
+        $set: { 'name.middle': 'Warner' },
         $push: { awards: {
                            award: 'IBM Fellow',
                            year: '1963',
@@ -392,6 +319,14 @@ When passed as an argument to the :method:`update()
       }
    )
 
+.. seealso::
+
+   - :ref:`update operators <update-operators>` page for the available
+     update operators and syntax.
+
+   - :doc:`update </applications/update>` for more examples on
+     update documents.
+
 For additional examples of updates that involve array elements,
 including where the elements are documents, see the :operator:`$`
 positional operator.
@@ -418,8 +353,9 @@ Index documents contain field and value pairs, in the following form:
 
 The following document specifies the :ref:`multi-key index
 <index-type-multi-key>` on the ``_id`` field and the ``last`` field
-contained in the subdocument ``name`` field; the document uses
-:term:`dot-notation` to access a field in a subdocument:
+contained in the subdocument ``name`` field. The document uses
+:ref:`dot notation <document-dot-notation>` to access a field in a
+subdocument:
 
 .. code-block:: javascript
 
@@ -478,8 +414,8 @@ method, the sort order document sorts the results of the
 .. _document-mongodb-type-considerations:
 .. _document-bson-type-considerations:
 
-BSON Types
-----------
+BSON Type Considerations
+------------------------
 
 The following BSON types require special consideration:
 
diff --git a/source/core/read-operations.txt b/source/core/read-operations.txt
index 985ae9b2bdc..70b189aa867 100644
--- a/source/core/read-operations.txt
+++ b/source/core/read-operations.txt
@@ -200,49 +200,13 @@ collection of documents named ``inventory``:
                                                { price: { $lt: 9.95 } } ]
                          } )
 
-.. _read-operations-dot-notation-arrays:
+.. _read-operations-subdocuments:
 
-*Arrays*
-
-When the field holds an array, you can query at the array level and at
-the element level:
-
-- Equality match at the array level will select documents if the array
-  matches exactly the specified array, including the element order. In
-  the following example, the query will match all documents where the
-  value of the field ``tags`` is an array with only three elements,
-  ``'fruit'``, ``'food'``, and ``'citrus'``, in that order:
-
-  .. code-block:: javascript
-
-     db.inventory.find( { tags: [ 'fruit', 'food', 'citrus' ] } )
-
-- Equality match at the element level can either check if the array
-  contains at least *one* element with the specified value or if the
-  element at a specified position equals the specified value.
-
-  In the following example, the query will match all documents where
-  the value of the field ``tags`` is an array that contains, as one of
-  its elements, the element ``'fruit'``:
-
-  .. code-block:: javascript
-
-     db.inventory.find( { tags: 'fruit' } )
-
-  In the following example, the query uses the :term:`dot-notation` to match
-  all documents where the value of the ``tags`` field is an array whose
-  first element equals ``'fruit'``:
-
-  .. code-block:: javascript
-
-     db.inventory.find( { 'tags.0' : 'fruit' } )
-
-.. _read-operations-dot-notation-subdocuments:
-
-*Subdocuments*
+Subdocuments
+````````````
 
 When the field holds a subdocument, you can query at the subdocument
-level or, with the use of :term:`dot-notation`, at the fields of the
+level or, with the use of :term:`dot notation`, at the fields of the
 subdocument level:
 
 - Equality match at the subdocument level will select documents if the
@@ -260,7 +224,7 @@ subdocument level:
                           producer: {
                                       company: 'ABC123',
                                       address: '123 Street'
-                                    } 
+                                    }
                         }
                       )
 
@@ -268,7 +232,7 @@ subdocument level:
   documents if the subdocument contains a field that matches the
   specified value:
 
-  In the following example, the query uses the :term:`dot-notation` to match
+  In the following example, the query uses the :term:`dot notation` to match
   all documents where the value of the field ``producer`` is a
   subdocument that contains a field ``company`` with the value
   ``'ABC123'`` and may contain other fields:
@@ -277,12 +241,51 @@ subdocument level:
 
      db.inventory.find( { 'producer.company': 'ABC123' } )
 
-.. _read-operations-dot-notation-array-of-subdocuments:
+.. _read-operations-arrays:
+
+Arrays
+````````
+
+When the field holds an array, you can query at the array level and at
+the element level:
+
+- Equality match at the array level will select documents if the array
+  matches exactly the specified array, including the element order. In
+  the following example, the query will match all documents where the
+  value of the field ``tags`` is an array with only three elements,
+  ``'fruit'``, ``'food'``, and ``'citrus'``, in that order:
+
+  .. code-block:: javascript
+
+     db.inventory.find( { tags: [ 'fruit', 'food', 'citrus' ] } )
+
+- Equality match at the element level can either check if the array
+  contains at least *one* element with the specified value or if the
+  element at a specified position equals the specified value.
+
+  In the following example, the query will match all documents where
+  the value of the field ``tags`` is an array that contains, as one of
+  its elements, the element ``'fruit'``:
+
+  .. code-block:: javascript
+
+     db.inventory.find( { tags: 'fruit' } )
+
+  In the following example, the query uses the :term:`dot notation` to match
+  all documents where the value of the ``tags`` field is an array whose
+  first element equals ``'fruit'``:
+
+  .. code-block:: javascript
+
+     db.inventory.find( { 'tags.0' : 'fruit' } )
+
+.. _read-operations-arrays-of-subdocuments:
 
-*Array of Subdocuments*
+Arrays of Subdocuments
+^^^^^^^^^^^^^^^^^^^^^^
 
 When a field contains an array of subdocuments you can use
-:term:`dot-notation` to query by the fields of the subdocument.
+:term:`dot notation` to query by the fields of the subdocument.
 
 - If you know the index position of the subdocument, you can specify
   the array position.
@@ -307,10 +310,10 @@ When a field contains an array of subdocuments you can use
      db.inventory.find( { 'memos.by': 'shipping' } )
 
 - To match by multiple fields in the subdocument, you can use either
-  dot-notation or the :doc:`$elemMatch </reference/operator/elemMatch>`
+  dot notation or the :doc:`$elemMatch </reference/operator/elemMatch>`
   operator:
 
-  The following example uses dot-notation to query for documents
+  The following example uses dot notation to query for documents
   where the value of the ``memos`` field is an array that has at least
   one subdocument that contains the field ``memo`` equal to ``'on time'``
   and the field ``by`` equal to ``'shipping'``:
@@ -442,7 +445,7 @@ operation:
    db.collection.ensureIndex( { <field1>: <order>, <field2>: <order>, ... } )
 
 - The ``field`` specifies the field to index. The field may be a field
-  from a subdocument, using :term:`dot-notation` to specify subdocument
+  from a subdocument, using :term:`dot notation` to specify subdocument
   fields.
 
   You can create an index on a single field or a :ref:`compound index
diff --git a/source/includes/fact-dot-notation.rst b/source/includes/fact-dot-notation.rst
new file mode 100644
index 00000000000..f34573b70df
--- /dev/null
+++ b/source/includes/fact-dot-notation.rst
@@ -0,0 +1,17 @@
+MongoDB uses the *dot notation* to access the elements of an array and
+to access the fields of a subdocument.
+
+To access an element of an array by the zero-based index position, you
+concatenate the array name with the dot (``.``) and zero-based index
+position:
+
+.. code-block:: javascript
+
+   '<array>.<index>'
+
+To access a field of a subdocument with *dot-notation*, you concatenate
+the subdocument name with the dot (``.``) and the field name:
+
+.. code-block:: javascript
+
+   '<subdocument>.<field>'
diff --git a/source/includes/fact-write-concern.rst b/source/includes/fact-write-concern.rst
index 32e3f53cc82..a35c38501fe 100644
--- a/source/includes/fact-write-concern.rst
+++ b/source/includes/fact-write-concern.rst
@@ -6,9 +6,5 @@ confirm the result of the write operation:
 
    { getLastError: 1 }
 
-Refer to the documentation on :ref:`write concern
-<write-operations-write-concern>` in the :doc:`/core/write-operations`
-section for more information.
-
 Refer to the documentation on :ref:`write concern <write-concern>` and
 :doc:`/core/write-operations` for more information.
diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt
index e1e626a0289..7f3f51818cf 100644
--- a/source/reference/glossary.txt
+++ b/source/reference/glossary.txt
@@ -904,21 +904,5 @@ Glossary
       disk. MongoDB calls ``fsync()`` on its database files at least
       every 60 seconds.
 
-   dot-notation
-      MongoDB uses the *dot-notation* to access the elements of an array and
-      to access the fields of a subdocument.
-
-      To access an element of an array by the zero-based index position, you
-      concatenate the array name with the dot (``.``) and zero-based index
-      position:
-
-      .. code-block:: javascript
-
-         '<array>.<index>'
-
-      To access a field of a subdocument with *dot-notation*, you concatenate
-      the subdocument name with the dot (``.``) and the field name:
-
-      .. code-block:: javascript
-
-         '<subdocument>.<field>'
+   dot notation
+      .. include:: /includes/fact-dot-notation.rst