Document the existence of v2, and v1 vs. v2 differences.

doc/intro.qbk

@@ -21,6 +21,12 @@ container requirements in the standard.  _IFaces_ provides another template
 called _cont_iface_ that reduces the implementation and testing burden
 dramatically.
 
+[note C++20 versions of _iter_iface_ and _cont_iface_ are provided (C++20
+provides `std::view_interface`).  These are constrained templates using C++20
+concepts.  These are in the `boost::stl_interfaces::v2` namespace, and are
+considered experimental, because at the time of this writing, no
+C++20-conforming compiler exists.]
+
 [heading A Quick Example]
 
 Here is an example of the iterator portion of the library.  Let's say that we

doc/stl_interfaces.qbk

@@ -65,6 +65,7 @@
 [def _CRTP_                [@https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern CRTP]]
 [def _Iterator_            [@https://www.boost.org/doc/libs/release/libs/iterator Boost.Iterator]]
 [def _Container_           [@https://www.boost.org/doc/libs/release/libs/container Boost.Container]]
+[def _cmcstl2_             [@https://github.com/CaseyCarter/cmcstl2 cmcstl2]]
 
 [def _emdash_              \u2014]
 

doc/tutorial.qbk

@@ -887,3 +887,74 @@ There's nothing much to document about it; it works just like
 `std::reverse_iterator`.
 
 [endsect]
+
+[section The `v2` Namespace]
+
+_IFace_ contains an `inline v1` namespace.  All the C++14-compatible
+*`_interface` templates are implemnted there.  Since `v1` is an `inline`
+namespace, you can just access these templates without referring to `v1` at
+all.
+
+In the `boost::stl_interfaces::v2` namespace, you will find C++20 versions of
+_iter_iface_ and _cont_iface_ are provided; the C++20 standard library
+provides `std::view_interface`.
+
+These are constrained templates using C++20 concepts, and are considered
+experimental, because at the time of this writing, no C++20-conforming
+compiler exists.
+
+For each template, you will find two versions: one that uses concepts and
+templates defined in the C++20 standard library, and one that uses concepts
+and templates defined in the _cmcstl2_ library.
+
+The first is the final version of the `v2` templates, for use with a
+conforming C++20 compiler and standard library.
+
+The second is a temporary implementation for those who wish to experiment with
+a concept-constrained version before C++20 is widely implemented.  _cmcstl2_
+is an implementation of the `std::ranges` portion of the C++20 standard
+library.  To use it:
+
+- put its headers in your include path, so that they can be included with
+  `#include <stl2/foo.hpp>`, and
+
+- build with GCC 8 or 9, including the `-fconcepts` and `-std=c++2a` flags.
+
+GCC 8 and 9 are the only compilers with an adequate concepts implementation at
+the time of this writing.
+
+[heading Differences between `v1` and `v2`]
+
+There are some differences between the `v1` and `v2` implementations, mostly
+due to the differences between SFINAE and concepts.  Most of these changes are
+subtle, and will not be noticeable.
+
+Differences you will probably notice:
+
+- _view_iface_ and _cont_iface_ each have a `bool` non-type template parameter
+  `Contiguous` that indicates whether they have a `begin()` operation that
+  yields a contiguous iterator.  Before C++20, there was no way of determining
+  that.  The `v2` versions do not need this template parameter.
+
+- The `insert(position, n, value)` overload of _cont_iface_ _emdash_ the one
+  that inserts `n` copies of `value` before `position` _emdash_ is
+  unconstrained.  That is because the proper constraint causes an infinite
+  recursion on every compiler I tried.  This means that containers that you
+  should not be able to `insert()` into will still have the `insert(position,
+  n, value)` overload.  The `v2` version is constrained with the identical
+  constraint, in concept form, and the constraint works as expected.
+
+Differnces you are less likely to notice:
+
+- In order to constrain all the member functions of the `v1` implementations
+  individually, it was necessary to make them templates.  Most (though not
+  all) of the `v2` member functions are not templates.
+
+- The constraints on member functions in `v1` are all SFINAE-based.  The
+  constraints on member functions in `v2` are all concept-based.
+
+The subtle differences between SFINAE and concepts and between templates and
+non-templates in overload resolution may mean that these less-noticable
+differences do affect your code, but this will be rare in practice.
+
+[endsect]