Add docs for new CXX11 option & mask option for Windows.

- The CXX11 option has no effect on Windows, as there, any new C++11
  features are enabled by default, as such to avoid confusion we only
  present the option for non-Windows.

Change-Id: I38925ae3bb8c16682d404468ba95c611a519b9b9

docs/source/building.rst

@@ -545,6 +545,51 @@ Options controlling Ceres configuration
    multi-threading with ``OpenMP`` is not supported. Turn this ``OFF``
    to disable multi-threading.
 
+#. ``CXX11 [Default: OFF]`` *Non-Windows platforms only*.
+
+   Although Ceres does not currently use C++11, it does use ``shared_ptr``
+   (required) and ``unordered_map`` (if available); both of which existed in the
+   previous iterations of what became the C++11 standard: TR1 & C++0x.  As such,
+   Ceres can compile on pre-C++11 compilers, using the TR1/C++0x versions of
+   ``shared_ptr`` & ``unordered_map``.
+
+   Note that on Linux (GCC & Clang), compiling against the TR1/C++0x versions:
+   ``CXX11=OFF`` (the default) *does not* require ``-std=c++11`` when compiling
+   Ceres, *nor* does it require that any client code using Ceres use
+   ``-std=c++11``.   However, this will cause compile errors if any client code
+   that uses Ceres also uses C++11 (mismatched versions of ``shared_ptr`` &
+   ``unordered_map``).
+
+   Enabling this option: ``CXX11=ON`` forces Ceres to use the C++11
+   versions of ``shared_ptr`` & ``unordered_map`` if they are available, and
+   thus imposes the requirement that all client code using Ceres also
+   compile with ``-std=c++11``.  This requirement is handled automatically
+   through CMake target properties on the exported Ceres target for CMake >=
+   2.8.12 (when it was introduced).  Thus, any client code which uses CMake will
+   automatically be compiled with ``-std=c++11``.  **On CMake versions <
+   2.8.12, you are responsible for ensuring that any code which uses Ceres is
+   compiled with** ``-std=c++11``.
+
+   On OS X 10.9+, Clang will use the C++11 versions of ``shared_ptr`` &
+   ``unordered_map`` without ``-std=c++11`` and so this option does not change
+   the versions detected, although enabling it *will* require that client code
+   compile with ``-std=c++11``.
+
+   The following table summarises the effects of the ``CXX11`` option:
+
+   ===================  ==========  ================  ======================================
+   OS                   CXX11       Detected Version  Ceres & client code require ``-std=c++11``
+   ===================  ==========  ================  ======================================
+   Linux (GCC & Clang)  OFF         tr1               **No**
+   Linux (GCC & Clang)  ON          std               **Yes**
+   OS X 10.9+           OFF         std               **No**
+   OS X 10.9+           ON          std               **Yes**
+   ===================  ==========  ================  ======================================
+
+   The ``CXX11`` option does does not exist for Windows, as there any new C++
+   features available are enabled by default, and there is no analogue of
+   ``-std=c++11``.
+
 #. ``BUILD_SHARED_LIBS [Default: OFF]``: By default Ceres is built as
    a static library, turn this ``ON`` to instead build Ceres as a
    shared library.