[doc] update docs

Author: h-2

README.md

@@ -3,15 +3,16 @@
 This library explores an opinionated re-design of C++ Range Adaptors, commonly referred to as "views". It tries to reduce complexity in the conceptual space and provide a better, more consistent user experience.
 At the same time, the usage patterns and naming remain close enough to the standard library to be used almost as a drop-in replacement.
 
+
 ## 🪞 Differences and similarities to std::ranges
 
 ```cpp
-auto adapted_range  =  original_range  |  range_adaptor_object  |  range_adaptor_object2;
+auto range_adaptor  =  underlying_range | range_adaptor_object | range_adaptor_object2;
 ```
 
-The general pattern for creating adapted ranges is the same in our library and in the standard library.
-However, we aim to establish clearer rules for what you can and cannot do with the `adapted_range`.
-To achieve this, we are sometimes stricter about what the `original_range` needs to provide.
+The general pattern for creating range adaptors is the same in our library and in the standard library.
+However, we aim to establish clearer rules for what you can and cannot do with the `range_adaptor`.
+To achieve this, we are sometimes stricter about what the `underlying_range` needs to provide.
 
 
 ### ⌨️ Summary for the casual C++ programmer
@@ -22,6 +23,7 @@ To achieve this, we are sometimes stricter about what the `original_range` needs
 * [Simpler types](./docs/simpler_types.md) and better error messages (at least we are trying :sweat_smile:).
 * Less confusion: you don't need to understand what a "view" is, because it is irrelevant for this library.
 
+
 ### 🤓 Summary for the Ranges nerd
 
 This library [fundamentally differentiates between multi-pass and single-pass ranges](./docs/range_properties.md).
@@ -36,28 +38,31 @@ This library [fundamentally differentiates between multi-pass and single-pass ra
   * This results in simpler types, fewer nested template instantiations, and avoids lots of special cases in the multi-pass implementations.
 
 
-## 📖 Further reading
-
-**Please have a look at the docs folder.**
-In particular, you may be interested in:
-
-* [Getting started](./docs/getting_started.md): short introduction on how to use this library and the terminology used in the documentation.
-* [Implementation status](./docs/implementation_status.md): overview of which adaptors are already available.
-* [Examples](./docs/examples.md): examples that illustrate standard library usage vs radr usage ("tony tables").
-* [Trade-offs](./docs/tradeoffs.md): things to be aware before switching to this library.
-
 ## 🗒️ Library facts
 
 * Easy to use: header-only and no dependencies
 * License: Apache with LLVM exception[^boost]
 * Compilers: GCC≥11 or Clang≥17
 * Standard libraries: both libstdc++ and libc++ are tested.
-* C++20 required.[^std]
+* Progress: all std::views from C++20 are reimplemented and many later ones
+* (Only) C++20 required.[^std]
 
 [^boost]: The file `generator.hpp` is licensed under the Boost Software license. It is used only if your standard library does not provide `std::generator`.
 
 [^std]: A bonus of using this library is getting access to the equivalent of C++23 and C++26 adaptors in a C++20-based codebase.
 
+
+## 📖 Further reading
+
+**Please have a look at the docs folder.**
+In particular, you may be interested in:
+
+* [Getting started](./docs/getting_started.md): short introduction on how to use this library and the terminology used in the documentation.
+* [Implementation status](./docs/implementation_status.md): overview of which adaptors are already available.
+* [Examples](./docs/examples.md): examples that illustrate standard library usage vs radr usage ("tony tables").
+* [Trade-offs](./docs/tradeoffs.md): things to be aware before switching to this library.
+
+
 ## 👪 Credits
 
 Not everything presented here is novel—in fact, many of the ideas are based on older "ranges" designs (e.g. old ISO papers, Boost ranges and old range-v3).

docs/getting_started.md

@@ -2,9 +2,11 @@
 
 The usage patterns of this library are almost identical to the standard library.
 
-Differences exist in handling some underlying ranges.
+* Just replace `std::views::FOO` with `radr::FOO`; see below for slight differences in range capture.
+* You can use all functions, algorithms and concepts from `std::ranges::` on our types.
+* Optionally, you can use `radr::begin()` / `radr::end()` instead of `std::ranges::begin()` / `std::ranges::end()`.
 
-## Quickstart
+## Capturing the underlying range
 
 ```cpp
 /* temporaries */
@@ -18,13 +20,13 @@ auto rad1 = std::move(vec1) | radr::take(2);            // this library
 
 /* refer to existing borrowed range */
 std::span s = vec1;
-auto vue2 =  s  | std::views::take(2);                  // standard library
-auto rad2 =  s  | radr::take(2);                        // this library
+auto vue2 = s | std::views::take(2);                    // standard library
+auto rad2 = s | radr::take(2);                          // this library
 
 /* refer to existing container */
 std::vector vec2{1, 2, 3};
 auto vue3 =          vec2  | std::views::take(2);       // standard library
-auto rad3 = std::ref(vec2) | radr::take(2);             // this library ← DIFFERENCE
+auto rad3 = std::ref(vec2) | radr::take(2);             // this library      ← ONLY DIFFERENCE!
 ```
 
 As you can see, only the syntax for creating an indirection is slightly different, i.e. when adapting an existing container, you need to explicitly state whether you want to `std::move()` or `std::ref()` it.
@@ -49,5 +51,5 @@ the *original range*.
 Our range adaptors can be created on any of these three categories, and will result in an adapted range of the same
 category, except that `std::ref()`-ing a container leads to a borrowed range (see the last example above).
 
-In particular, it should be noted that *adapted ranges* are not a separate category and no range properties are specific to them; e.g. an adaptor on a `std::string_view` (a borrowed range) is also just a borrowed range—while an adaptor on a `std::vector` (first example above) is also just a "container".
+In particular, it should be noted that *range adaptors* are not a separate category and no range properties are specific to them; e.g. an adaptor on a `std::string_view` (a borrowed range) is also just a borrowed range—while an adaptor on a `std::vector` (first example above) is also just a "container".
 We do not use the term "view" and the formal and informal definitions of "view" and "viewable range" are irrelevant for this library.

docs/implementation_status.md

@@ -4,6 +4,7 @@ This library is a **work-in-progress**.
 We try to stay close to standard library interfaces, but we neither promise full API compatibility with `std::ranges::` nor do we currently promise stability between releases of this library.
 The latter will likely change at some point.
 
+
 ## Range adaptor classes
 
 
@@ -16,6 +17,7 @@ The latter will likely change at some point.
 There are no distinct type templates per adaptor (like e.g. `std::ranges::transform_view` for `std::views::transform` in the standard library).
 Instead all range adaptor objects in this library (see below) return a specialisation of one of the above type templates.
 
+
 ## Range adaptor objects
 
 We plan to add equivalent objects for all standard library adaptors.
@@ -41,22 +43,22 @@ We plan to add equivalent objects for all standard library adaptors.
 | `radr::transform(fn)`    | C++20 | | `std::views::transform`        | C++20     |                                          |
 | `radr::values`           | C++20 | | `std::views::values`           | C++20     |                                          |
 
-
 All range adaptors from this library are available in C++20, although `radr::as_rvalue` behaves slightly different between modes.
 
 [^diff]: These range adaptors have relevant differences between `std::` and `radr::`. Usually the names have been chosen differently to highlight this.
 
+
 ## Range factory objects
 
-| Range factories               | Equivalent in `std::`   | Remarks                                              |
-|-------------------------------|-------------------------|------------------------------------------------------|
-| `radr::empty<T>`              | `std::views::empty`     |                                                      |
-| `radr::iota(val[, bound])`    | `std::views::iota`      | multi-pass version of iota                           |
-| `radr::iota_sp(val[, bound])` | `std::views::iota`      | single-pass version of iota                          |
-| `radr::istream<Val>`          | `std::views::istream`   |                                                      |
-| `radr::istream<Val>`          | `std::views::istream`   |                                                      |
-| `radr::repeat(val[, bound])`  | `std::views::repeat`    | allows indirect storage and static bounds            |
-| `radr::single(val)`           | `std::views::single`    | allows indirect storage                              |
+| Range factories (objects)     | C++XY | | Equivalent in `std::`   | C++XY     | Remarks                                   |
+|-------------------------------|-------|-|-------------------------|-----------|-------------------------------------------|
+| `radr::empty<T>`              | C++20 | | `std::views::empty`     | C++20     |                                           |
+| `radr::iota(val[, bound])`    | C++20 | | `std::views::iota`      | C++20     | multi-pass version of iota                |
+| `radr::iota_sp(val[, bound])` | C++20 | | `std::views::iota`      | C++20     | single-pass version of iota               |
+| `radr::istream<Val>`          | C++20 | | `std::views::istream`   | C++20     |                                           |
+| `radr::repeat(val[, bound])`  | C++20 | | `std::views::repeat`    | **C++23** | allows indirect storage and static bounds |
+| `radr::single(val)`           | C++20 | | `std::views::single`    | C++20     | allows indirect storage                   |
+
 
 ## Notable functions