Split the json_view feature page into sub-pages (#6018)

* Split the json_view feature page into sub-pages

The single features/json_view.md page grew to ~600 lines covering eight
topics. Split it into features/json_view/ with an overview page and
pages for ownership and lifetime, differences from basic_json, reading
values, generic code, editing, and images.

The new differences page collects what was spread over several sections
("What is the same", "What is different", "Duplicate keys", and notes in
the conversion and serialization sections) under one summary table, and
adds the parts of the basic_json interface a view does not have. The
other pages now link to it instead of restating the rules.

Internal links across the documentation point to the new pages.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Docs: fix stale comments and trim repeated text in json_view pages

- fig-jsonview.js/.css: point the header comments at the new pages
- reading.md: views' strings are valid as long as the document (and a
  borrowed source text), as lifetime.md says
- reading.md, generic_code.md: link to differences.md instead of
  restating the member-order and repeated-key rules
- differences.md: drop the third mention of ordering comparisons, name
  rbegin()/rend() in the iterator row
- exceptions.md: link editable documents to editing.md

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/basic_json_view/at.md

@@ -92,7 +92,7 @@ Pointer path of the value within the document, and with
 
     If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
     [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
-    `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
+    `operator[]` and [Duplicate keys](../../features/json_view/differences.md#duplicate-keys) for the reasons and for how to get
     the last value.
 
 Unlike [`operator[]`](operator[].md), which returns a [discarded](is_discarded.md) view for a missing key or an

docs/mkdocs/docs/api/basic_json_view/basic_json_view.md

@@ -58,7 +58,7 @@ placeholder for "no value yet" and later be assigned a real view.
 - [`is_discarded`](is_discarded.md) - return whether the view is invalid
 - [`root`](../basic_json_document/root.md) - the view of a document's root value
 - [`view_mode`](../view_mode.md) - whether a document and its views can be edited
-- [Zero-copy JSON views](../../features/json_view.md#ownership-and-lifetime) - how long a view stays valid
+- [Zero-copy JSON views](../../features/json_view/lifetime.md) - how long a view stays valid
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/contains.md

@@ -47,7 +47,7 @@ No-throw guarantee: this function never throws exceptions.
 
     If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
     [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
-    `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
+    `operator[]` and [Duplicate keys](../../features/json_view/differences.md#duplicate-keys) for the reasons and for how to get
     the last value.
 
 Overload 1 always returns `#!cpp false` when the value is not an object — including a [discarded](is_discarded.md)

docs/mkdocs/docs/api/basic_json_view/dump.md

@@ -70,7 +70,7 @@ except that `#!cpp -0` is written as `#!cpp 0`, the way [`BasicJsonType::parse()
 `#!cpp number_format::source` copies every number exactly as written in the source text instead, with no exception
 for `#!cpp -0` — `#!cpp 1.50`, `#!cpp 1E2`, `#!cpp -0.0`, `#!cpp -0`, or all digits of an integer literal with more
 digits than any number type holds (such a literal is itself classified as a float, see
-[What is different](../../features/json_view.md#what-is-different)) — something `BasicJsonType` cannot do, since
+[What is different](../../features/json_view/differences.md)) — something `BasicJsonType` cannot do, since
 parsing already reduces every number to its parsed value.
 
 ## Examples
@@ -98,7 +98,7 @@ parsing already reduces every number to its parsed value.
 - [`operator<<`](operator_ltlt.md) - serialize this value to a stream
 - [`materialize`](materialize.md) - build a `BasicJsonType` value, e.g. to use `BasicJsonType::dump`'s `error_handler`
 - [`BasicJsonType::dump`](../basic_json/dump.md) - the corresponding function of `basic_json`
-- [Zero-copy JSON views](../../features/json_view.md#writing-a-view-back) - writing a view back without building a tree
+- [Zero-copy JSON views](../../features/json_view/reading.md#writing-a-view-back) - writing a view back without building a tree
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/find.md

@@ -37,7 +37,7 @@ constant time on average.
 
     If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
     [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
-    `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
+    `operator[]` and [Duplicate keys](../../features/json_view/differences.md#duplicate-keys) for the reasons and for how to get
     the last value.
 
 Unlike [`BasicJsonType::find`](../basic_json/find.md), which always returns `#!cpp end()` for a non-object type, this

docs/mkdocs/docs/api/basic_json_view/get.md

@@ -39,14 +39,14 @@ as [`BasicJsonType::parse()`](../basic_json/parse.md) does), as well as the type
 accept views, e.g. with [`is_json_view`](../is_json_view.md). A `from_json()` that also accepts types that are no JSON
 values at all, such as the unconstrained `#!cpp template<typename BasicJsonType> void from_json(const BasicJsonType&,
 T&)` of [arbitrary type conversions](../../features/arbitrary_types.md), is not called with a view: it may use
-`BasicJsonType` functions a view does not have. See [Writing generic code](../../features/json_view.md#writing-generic-code).
+`BasicJsonType` functions a view does not have. See [Writing generic code](../../features/json_view/generic_code.md).
 
 !!! warning "Duplicate keys"
 
     Such a `from_json()` looks members up in the view, where a repeated key finds the **first** member, while
     `#!cpp materialize().get<T>()` sees the **last** one, as [`BasicJsonType::parse()`](../basic_json/parse.md)
     keeps it: for `#!cpp {"x":1,"x":2}`, `#!cpp get<point>()` reads `#!cpp x == 1`. See
-    [Duplicate keys](../../features/json_view.md#duplicate-keys).
+    [Duplicate keys](../../features/json_view/differences.md#duplicate-keys).
 
 Every other `T` — user types whose `from_json()` is written for `BasicJsonType` only, types without a default
 constructor, `#!cpp std::tuple`s holding references, ... — is converted by `#!cpp materialize().get<T>()`: the subtree is built into a real `BasicJsonType`
@@ -152,7 +152,7 @@ instead: its path is relative to the root of the view's subtree, because `materi
 - [`number_token`](number_token.md) - a number's token text, without a copy
 - [`materialize`](materialize.md) - build the `BasicJsonType` value of this subtree
 - [`BasicJsonType::get`](../basic_json/get.md) - the corresponding function of `basic_json`
-- [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - which conversions avoid building a basic_json value
+- [Zero-copy JSON views](../../features/json_view/reading.md#getting-values-out-without-copying) - which conversions avoid building a basic_json value
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/get_string.md

@@ -70,7 +70,7 @@ since floating-point values and unescaped strings are read from the source lazil
 - [`get`](get.md) - convert the value to a given type (`#!cpp get<string_view_t>()` is equivalent to this function)
 - [`number_token`](number_token.md) - a number's token text, without a copy
 - [`BasicJsonType::get_ref`](../basic_json/get_ref.md) - the closest counterpart of `basic_json`
-- [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - borrowing strings instead of copying them
+- [Zero-copy JSON views](../../features/json_view/reading.md#getting-values-out-without-copying) - borrowing strings instead of copying them
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/get_to.md

@@ -75,7 +75,7 @@ them with those of a default-constructed `T`.
 
 - [`get`](get.md) - convert the value to a given type
 - [`BasicJsonType::get_to`](../basic_json/get_to.md) - the corresponding function of `basic_json`
-- [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - which conversions avoid building a basic_json value
+- [Zero-copy JSON views](../../features/json_view/reading.md#getting-values-out-without-copying) - which conversions avoid building a basic_json value
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/index.md

@@ -147,7 +147,7 @@ still refers to it — including ones taken before the change — reads the new
 
 ## See also
 
-- [Zero-copy JSON views](../../features/json_view.md) - guide to documents and views
+- [Zero-copy JSON views](../../features/json_view/index.md) - guide to documents and views
 - [`basic_json_document`](../basic_json_document/index.md) - the document that owns the parsed data
 - [`json_view`](../json_view.md) - and [`json_editable_view`](../json_editable_view.md) - the default specializations
 - [`materialize`](materialize.md) - build a `basic_json` value from a view

docs/mkdocs/docs/api/basic_json_view/is_discarded.md

@@ -54,7 +54,7 @@ A `basic_json_view` is not convertible to `#!cpp bool`: such a conversion would
 - [`(constructor)`](basic_json_view.md) - the default constructor creates a discarded view
 - [`basic_json_document::is_discarded`](../basic_json_document/is_discarded.md) - return whether the last parse failed
 - [`BasicJsonType::is_discarded`](../basic_json/is_discarded.md) - the corresponding function of `basic_json`
-- [Zero-copy JSON views](../../features/json_view.md#what-is-different) - how views differ from basic_json
+- [Zero-copy JSON views](../../features/json_view/differences.md) - how views differ from basic_json
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/materialize.md

@@ -78,7 +78,7 @@ never caches the result.
 - [`root`](../basic_json_document/root.md) - the view of a document's root value
 - [`BasicJsonType::parse`](../basic_json/parse.md) - build a `BasicJsonType` value directly from a JSON text
 - [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) - source positions on parsed values
-- [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - when to build a basic_json value from a view
+- [Zero-copy JSON views](../../features/json_view/reading.md#getting-values-out-without-copying) - when to build a basic_json value from a view
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/number_format.md

@@ -45,7 +45,7 @@ source
 - [`number_token`](number_token.md) - get a single number's token text without dumping the whole value
 - [`BasicJsonType::error_handler_t`](../basic_json/error_handler_t.md) - the analogous enumeration for
   `BasicJsonType::dump`'s decoding-error behavior
-- [Zero-copy JSON views](../../features/json_view.md#writing-a-view-back) - writing numbers as they appeared in the source
+- [Zero-copy JSON views](../../features/json_view/reading.md#writing-a-view-back) - writing numbers as they appeared in the source
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/number_token.md

@@ -68,7 +68,7 @@ buffer — and is valid exactly as long as that text is, see the [validity rules
 - [`BasicJsonType::number_integer_t`](../basic_json/number_integer_t.md),
   [`number_unsigned_t`](../basic_json/number_unsigned_t.md), [`number_float_t`](../basic_json/number_float_t.md) - the
   number types `#!cpp get<T>()` and `materialize()` convert into
-- [Zero-copy JSON views](../../features/json_view.md#getting-values-out-without-copying) - reading a number exactly as written
+- [Zero-copy JSON views](../../features/json_view/reading.md#getting-values-out-without-copying) - reading a number exactly as written
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/operator[].md

@@ -120,7 +120,7 @@ document.
     [`materialize()`](materialize.md) or iterate the members with [`items()`](items.md) and keep the last match.
     The key hash index of a larger object (128 members or more) leads to the first member of a key as well.
     [`begin()`](begin.md)/[`end()`](end.md) and [`items()`](items.md) iterate over *all* members, including
-    duplicates, in document order. See [Duplicate keys](../../features/json_view.md#duplicate-keys) and
+    duplicates, in document order. See [Duplicate keys](../../features/json_view/differences.md#duplicate-keys) and
     [`size()`](size.md#notes).
 
 !!! info "JSON pointer resolution"

docs/mkdocs/docs/api/basic_json_view/operator_eq.md

@@ -19,7 +19,7 @@ Neither overload builds a `BasicJsonType` value for a view to do the comparison
 compare by value across their types (`#!cpp 1 == 1.0`), and an object compares by its members, with duplicate keys
 resolved exactly as `parse()` resolves them — the last value, at the position of the first occurrence of the key.
 This is not what [`operator[]`](operator[].md) and the other lookups return for a duplicate key: they find the *first*
-member (see [Duplicate keys](../../features/json_view.md#duplicate-keys)).
+member (see [Duplicate keys](../../features/json_view/differences.md#duplicate-keys)).
 
 ## Parameters
 

docs/mkdocs/docs/api/basic_json_view/operator_ltlt.md

@@ -68,7 +68,7 @@ Linear, as [`dump`](dump.md#complexity).
 - [`dump`](dump.md) - serialize to a JSON-formatted string
 - [`operator<<(std::ostream&)`](../operator_ltlt.md) - the corresponding operator for `basic_json`
 - [`JSON_NO_IO`](../macros/json_no_io.md) - switch off functions relying on certain C++ I/O headers
-- [Zero-copy JSON views](../../features/json_view.md#writing-a-view-back) - writing a view back without building a tree
+- [Zero-copy JSON views](../../features/json_view/reading.md#writing-a-view-back) - writing a view back without building a tree
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/source_offset.md

@@ -49,7 +49,7 @@ string, whose token length is not the same as its decoded [`size()`](size.md).
 
 - [`source`](../basic_json_document/source.md) - the parsed text
 - [`is_string`](is_string.md) - return whether the value is a string
-- [Zero-copy JSON views](../../features/json_view.md#images) - images and the source text
+- [Zero-copy JSON views](../../features/json_view/images.md) - images and the source text
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json_view/value.md

@@ -84,7 +84,7 @@ Pointer path of the value within the document, and with
 
     If the source text repeats a key, this resolves to the *first* member with it, not to the last one that
     [`materialize()`](materialize.md) and `parse()` keep. See the [Notes on duplicate keys](operator[].md#notes) of
-    `operator[]` and [Duplicate keys](../../features/json_view.md#duplicate-keys) for the reasons and for how to get
+    `operator[]` and [Duplicate keys](../../features/json_view/differences.md#duplicate-keys) for the reasons and for how to get
     the last value.
 
 !!! info "Differences to `at` and `operator[]`"