DOCS-1074 add note about using 2.2 syntax for multi and upsert options

source/core/create.txt

@@ -379,14 +379,17 @@ argument to determine the write operation:
 - If the query matches no document in the collection, the operation is
   an :doc:`insert </core/create>`.
 
-An upsert operation has the following syntax:
+An upsert operation has the following syntax [#previous-versions-upsert]_:
 
 .. code-block:: javascript
 
    db.collection.update( <query>,
                          <update>,
                          { upsert: true } )
 
+.. [#previous-versions-upsert]
+   .. include:: /includes/fact-upsert-multi-options.rst
+
 Insert a Document that Contains ``field`` and ``value`` Pairs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -398,7 +401,7 @@ specified in the ``<update>`` argument. If query does not include an
 unique ``ObjectId`` for its value.
 
 The following update inserts a new document into the
-``bios`` collection:
+``bios`` collection [#previous-versions-upsert]_:
 
 .. code-block:: javascript
 
@@ -440,7 +443,7 @@ the fields and values from ``<query>`` argument with the operations
 from the ``<update>`` argument applied.
 
 The following operation inserts a new document into the ``bios``
-collection:
+collection [#previous-versions-upsert]_:
 
 .. code-block:: javascript
 

source/core/update.txt

@@ -47,7 +47,8 @@ collection. The :method:`~db.collection.update()` method can either
 replace the existing document with the new document or update specific
 fields in the existing document.
 
-The :method:`~db.collection.update()` has the following syntax:
+The :method:`~db.collection.update()` has the following syntax
+[#previous-version]_:
 
 .. code-block:: javascript
 
@@ -69,6 +70,10 @@ The :method:`~db.collection.update()` has the following syntax:
    option, :method:`~db.collection.update()` method would correspond to
    the SQL ``UPDATE`` statement without the ``LIMIT`` clause.
 
+.. [#previous-version] This section uses the 2.2 interface to specify
+   the ``multi`` and the ``upsert`` options in a document form.
+   .. include:: /includes/fact-upsert-multi-options.rst
+
 Modify with Update Operators
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -220,13 +225,13 @@ Update Multiple Documents
 `````````````````````````
 
 If the ``<options>`` argument contains the ``multi`` option set to
-``true`` or ``1``, the :method:`~db.collection.update()`
-method updates all documents that match the query.
+``true`` or ``1``, the :method:`~db.collection.update()` method updates
+all documents that match the query.
 
 The following operation queries the ``bios`` collection for all
 documents where the ``awards`` field contains a subdocument element
 with the ``award`` field equal to ``Turing`` and sets the ``turing``
-field to ``true`` in the matching documents:
+field to ``true`` in the matching documents [#previous-versions-multi]_:
 
 .. code-block:: javascript
 
@@ -236,6 +241,9 @@ field to ``true`` in the matching documents:
       { multi: true }
    )
 
+.. [#previous-versions-multi]
+   .. include:: /includes/fact-upsert-multi-options.rst
+
 Replace Existing Document with New Document
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -277,7 +285,7 @@ with the fields in the ``<update>`` argument:
 If you set the ``upsert`` option in the ``<options>`` argument to
 ``true`` or ``1`` and no existing document match the ``<query>``
 argument, the :method:`~db.collection.update()` method can
-insert a new document into the collection.
+insert a new document into the collection. [#previous-versions-upsert]_
 
 The following operation queries the ``bios`` collection for a document
 with the ``_id`` field equal to ``11`` and the ``name`` field equal to
@@ -316,6 +324,9 @@ with the operations from the ``<update>`` argument applied.
 See also :ref:`Update Operations with the Upsert Flag
 <crud-create-update>` in the :doc:`/core/create` document.
 
+.. [#previous-versions-upsert] 
+   .. include:: /includes/fact-upsert-multi-options.rst
+
 .. [#upsert-update-operators] If the ``<update>`` argument includes
   only field and value pairs, the new document contains the fields and
   values specified in the ``<update>`` argument. If the ``<update>``

source/includes/fact-upsert-multi-options.rst

@@ -0,0 +1,4 @@
+Prior to version 2.2, in the :program:`mongo` shell, you would specify
+the ``upsert`` and the ``multi`` options in the
+:method:`~db.collection.update()` method as positional boolean options.
+See :method:`~db.collection.update()` for details.